5.3. Documentation generation tools
Rather than having to manually open reStructuredText or Markdown text files individually, we can use a documentation generation tool to help us organise and render our documentation in HTML or PDF format.
Sphinx is a powerful documentation generation tool that uses the Docutils python library for processing documentation mark up language files. It has many features for writing technical documentation including:
generates web pages, printable PDFs, documents for e-readers (ePub), and more, all from the same source files;
supports reStructuredText (default) or Markdown (enabled via an extension);
a system for cross-referencing documentation;
ability to embed existing code from source files into documentation (without needing to duplicate the code); and
support for extensions (e.g. adding bibliography support, automated creation of API’s from docstrings).
This documentation can then be hosted on the web for others to access. For example, third-party services such as ReadTheDocs.org provides free hosting of open-source documentation (see the Hosting documentation Section for more information). Other options are available for hosting private source code.
Extra reading
To find out about the differences between reST, docutils, readthedocs, sphinx, and extensions, see this link.
References
- mar
Daring Fireball: Markdown Syntax Documentation. URL: https://daringfireball.net/projects/markdown/syntax#philosophy (visited on 2021-05-06).
- doc
Introduction — Documentation system documentation. URL: https://documentation.divio.com/introduction/ (visited on 2021-05-06).
- sna21
Snake case. February 2021. Page Version ID: 1007486237. URL: https://en.wikipedia.org/w/index.php?title=Snake_case&oldid=1007486237 (visited on 2021-05-01).
- Atl
Atlassian. What is version control \textbar Atlassian Git Tutorial. URL: https://www.atlassian.com/git/tutorials/what-is-version-control (visited on 2021-05-01).