Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Engage 2019 Software documentation is fun if you have the right tools: Introducing Sphinx

147 views

Published on

Presentation held by Andrew Magerman, IBM Champion 2016-2019, at Engage 2019 on May 15th at Autoworld in Brussels

Published in: Technology
  • Be the first to comment

Engage 2019 Software documentation is fun if you have the right tools: Introducing Sphinx

  1. 1. Software Documentation is fun if you have the proper tools Introducing Sphinx 1#engageug
  2. 2. Write documentation that • is inviting and clear • is comprehensive, detailing all aspects of the project • is skimmable • offers examples of how to use the software • has repetition, when useful • is up-to-date • is easy to contribute to • is easy to find Source: https://www.oreilly.com/ideas/the-eight-rules-of-good-documentation 2#engageug
  3. 3. About Me Andrew Magerman IBM Champion 2016-2019 Organises the Swiss Notes User Group (this November) 3#engageug
  4. 4. Mandate 2018: document AlohaDXP 4#engageug
  5. 5. Tools we don’t want • Word – too much magic • Wikis – no control over formatting, no transferability • Markdown? • Too many flavours • References and cross-references soon become a pain • There is a plaintext markup language specifically for software documentation: reStructuredText • And a documentation generation tool: Sphinx 5#engageug
  6. 6. reStructuredText • Silly name • Single Version! • Very pithy • Contains *directives* = ‘commands’ Pycharm and Visual code have syntax highlighting 6#engageug
  7. 7. Introducing Sphinx • Open Source • Originally for Python documentation • Getting traction in other tech • Uses reStructuredText + additional directives • Appearance controlled by themes 7#engageug
  8. 8. classic theme 8#engageug
  9. 9. sphinxdoc theme 9#engageug
  10. 10. alabaster theme 10#engageug
  11. 11. sphinx-rtd-theme 11#engageug
  12. 12. custom theme 12#engageug
  13. 13. Sphinx Advantages • Output formats: • pdf through LaTeX • searchable website • Hierarchical Structure • Syntax highlighting • References and Cross-References • Version Control 13#engageug
  14. 14. code-block and literalinclude 14#engageug
  15. 15. tables 15#engageug
  16. 16. refs + structure + admonition 16#engageug
  17. 17. glossary 17#engageug
  18. 18. make latexpdf 18#engageug
  19. 19. Installing Sphinx – the pain, the pain • Download half the internet • Install Python 3 • Install sphinx-doc • Install LaTeX • Install sphinx-autobuild • Make sure you run python within a virtual environment • or die a thousand dependency deaths 19#engageug
  20. 20. Controlling Sphinx • sphinx-quickstart creates the directory structure • defaults are good • Root: _build, Makefile, make.bat, conf.py, index.rst • sphinx-build builds the output • Nice wrapper Makefile for it • make clean html latexpdf 20#engageug
  21. 21. sphinx-autobuild for live updates • watches a directory and triggers a new rendering • Good with two screens 21#engageug
  22. 22. Customizing sphinx-doc with conf.py • conf.py – always gets executed • add sphinx extensions (e.g. graphviz) • determine theme and theme options • pointer to static files (like css..) • LaTeX customiziations 22#engageug
  23. 23. Which editor? • My favourite: PyCharm • good syntax highlighting • good renederer, Sphinx directives not supported • VIsual Code has also renderers 23#engageug
  24. 24. Gotchas • Python • use a virtual environment. • reStructuredText • A completely empty line separates paragraphs • Two lines for rendering of code-block • Indentation is important! • Parameters for attributes must have the same indentation • an indent is three spaces 24#engageug
  25. 25. What about hosting? • readthedocs.org provides free hosting of your documentation • Can link a Webhook for continuous documentation • new push to master  new docs 25#engageug
  26. 26. Want developers to write documentation? • Don’t make them switch context • Don’t force them to use tools they hate • Don’t make them think about presentation and prettiness • When I presented Sphinx to the developers… 26#engageug
  27. 27. The eight rules of good documentation • Write documentation that • is inviting and clear • is comprehensive, detailing all aspects of the project • is skimmable • offers examples of how to use the software • has repetition, when useful • is up-to-date • is easy to contribute to • is easy to find Source: https://www.oreilly.com/ideas/the-eight-rules-of-good-documentation 27#engageug
  28. 28. Links • reStructuredText: • http://docutils.sourceforge.net/rst.html • sphinx: • http://www.sphinx-doc.org/en/master/ • sphinx-autobuild: • https://pypi.org/project/sphinx-autobuild/ • Python virtual environment: • https://docs.python.org/3/library/venv.html 28#engageug
  29. 29. About Me Andrew Magerman andrew@magerman.com IBM Champion 2016-2019 Organises the Swiss Notes User Group (this November) 29#engageug

×