There are many ways out there in the world to structure documentation, turning it into readable online docs. In order to ensure that things are consistent, we’ve settled on one standard across our projects, which this section will cover.
For formatting, we use ReST (reStructuredText), which is similar in many ways to Markdown. This is used to apply basic formatting (bold, italic, etc.), define links, lists, tables, and so on.
We generate our ReST-based documentation using Sphinx, a Python documentation generation tool with support for multiple languages.
For defining function arguments, return types, exceptions, etc., we use a variant of the Google Python Docstring standard, which this will go into further. We use the same format for all languages we work with, in order to ensure a consistent documentation standard.
reStructuredText, or ReST, is a bit like Markdown, in that it lets you apply formatting and structured content in a standard, text-based way. It differs a bit in how it does this, and it goes even further and offers a level of extensibility for defining special formatting options.
We use an enhanced version of ReST, provided by Sphinx, which offers a bunch of additions for documenting source code. Most of these additions won’t be needed for most docs, but are there for the special cases.
You’ll want to familiarize yourself with the basics of ReST, the Sphinx ReST additions and Sphinx Domains (which is used for codebase docs).
Practically everything you document is going to follow a one-line summary, multi-line description format. The one-line summary (which must not wrap) should briefly describe the purpose of the thing being documented, with the optional multi-line description providing additional details and zero or more special sections.