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