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

1. Software Documentation is fun if you have the proper tools Introducing Sphinx 1#engageug

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. About Me Andrew Magerman IBM Champion 2016-2019 Organises the Swiss Notes User Group (this November) 3#engageug

4. Mandate 2018: document AlohaDXP 4#engageug

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. reStructuredText • Silly name • Single Version! • Very pithy • Contains *directives* = ‘commands’ Pycharm and Visual code have syntax highlighting 6#engageug

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. classic theme 8#engageug

9. sphinxdoc theme 9#engageug

10. alabaster theme 10#engageug

11. sphinx-rtd-theme 11#engageug

12. custom theme 12#engageug

13. Sphinx Advantages • Output formats: • pdf through LaTeX • searchable website • Hierarchical Structure • Syntax highlighting • References and Cross-References • Version Control 13#engageug

14. code-block and literalinclude 14#engageug

15. tables 15#engageug

16. refs + structure + admonition 16#engageug

17. glossary 17#engageug

18. make latexpdf 18#engageug

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. 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. sphinx-autobuild for live updates • watches a directory and triggers a new rendering • Good with two screens 21#engageug

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. Which editor? • My favourite: PyCharm • good syntax highlighting • good renederer, Sphinx directives not supported • VIsual Code has also renderers 23#engageug

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. 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. 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. 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. 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. About Me Andrew Magerman andrew@magerman.com IBM Champion 2016-2019 Organises the Swiss Notes User Group (this November) 29#engageug