- We have gone to great lengths to retain compatibility with the standard library cmd, the documentation should make it easy for developers to understand how to move from cmd to cmd2, and what benefits that will provide
- We should provide both descriptive and reference documentation.
- API reference documentation should be generated from docstrings in the code
- Documentation should include rich hyperlinking to other areas of the documentation, and to the API reference
Use doc8 to check the style of the documentation. This tool can be invoked using the proper options by typing:
$ invoke doc8
All source files in the documentation must:
- have all lower case file names
- if the name has multiple words, separate them with an underscore
- end in ‘.rst’
In reStructuredText all indenting is significant. Use 2 spaces per indenting level.
Hard wrap all text so that line lengths are no greater than 79 characters. It makes everything easier when editing documentation, and has no impact on reading documentation because we render to html.
Titles and Headings¶
reStructuredText allows flexibility in how headings are defined. You only have to worry about the heirarchy of headings within a single file. Sphinx magically handles the intra-file heirarchy on it’s own. This magic means that no matter how you style titles and headings in the various files that comprise the documentation, Sphinx will render properly structured output. To ensure we have a similar consistency when viewing the source files, we use the following conventions for titles and headings:
1. When creating a heading for a section, do not use the overline and underline syntax. Use the underline syntax only:
Document Title ==============
2. The string of adornment characters on the line following the heading should be the same length as the title.
3. The title of a document should use the ‘=’ adornment character on the next line and only one heading of this level should appear in each file.
4. Sections within a document should have their titles adorned with the ‘-‘ character:
Section Title -------------
5. Subsections within a section should have their titles adorned with the ‘~’ character:
Subsection Title ~~~~~~~~~~~~~~~~
6. Use two blank lines before every title unless it’s the first heading in the file. Use one blank line after every heading.
7. If your document needs more than three levels of sections, break it into separate documents.
This documentation declares
python as the default Sphinx domain. Python
code or interactive Python sessions can be presented by either:
- finishing the preceding paragraph with a
::and indenting the code
- use the
If you want to show non-Python code, like shell commands, then use
The API documentation is mostly pulled from docstrings in the source code using
the Sphinx autodoc
extension. However, Sphinx has issues generating documentation for instance
attributes (see cmd2 issue 821 for the full discussion). We
have chosen to not use code as the source of instance attribute documentation.
Instead, it is added manually to the documentation files in
cmd2/docs/api/cmd.rst to see how to add documentation for an attribute.
For module data members and class attributes, the
autodoc extension allows
documentation in a comment with special formatting (using a #: to start the
comment instead of just #), or in a docstring after the definition. This
project has standardized on the docstring after the definition approach. Do not
use the specially formatted comment approach.
Whenever you reference
cmd2 in the documentation, enclose it in double
backticks. This indicates an inline literal in restructured text, and makes it
stand out when rendered as html.