Successfully reported this slideshow.

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

1

Share

Upcoming SlideShare
Ruby On Rails Basics
Ruby On Rails Basics
Loading in …3
×
1 of 29
1 of 29

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

1

Share

Download to read offline

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

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

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

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

Editor's Notes

  • We’ll see some examples later
  • I wouldn’t fiddle too much with the Themes
  • man pages, ePub


    Let’s go through some code examples. I was not brave enough to live-code. I’m
  • ×