SlideShare uses cookies to improve functionality and performance, and to provide you with relevant advertising. If you continue browsing the site, you agree to the use of cookies on this website. See our User Agreement and Privacy Policy.
SlideShare uses cookies to improve functionality and performance, and to provide you with relevant advertising. If you continue browsing the site, you agree to the use of cookies on this website. See our Privacy Policy and User Agreement for details.
Successfully reported this slideshow.
Activate your 14 day free trial to unlock unlimited reading.
Engage 2019 Software documentation is fun if you have the right tools: Introducing Sphinx
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
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
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
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