Documentation Conventions

Guiding Principles

Follow the Documentation Principles described by Write The Docs

In addition:

  • 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

Naming Files

  • all lower case file names
  • if the name has multiple words, separate them with an underscore
  • all documentation file names end in ‘.rst’

Heirarchy of headings

show the heirarchy of sphinx headings we use, and the conventions (underline only, no overline)

Use ‘=’, then ‘-‘, then ‘~’. If your document needs more levels than that, break it into separate documents.

You only have to worry about the heirarchy of headings within a single file. Sphinx handles the intra-file heirarchy magically on it’s own.

Use two blank lines before every heading unless it’s the first heading in the file. Use one blank line after every heading

Code

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 .. code-block:: directive

If you want to show other code, like shell commands, then use .. code-block: shell.

Table of Contents and Captions

Autolinking

Referencing cmd2 API documentation

Info and Warning Callouts

Wrapping

Hard wrap all text with line lengths no greater than 79 characters. It makes everything easier when editing documentation, and has no impact on reading documentation because we render to html.

Referencing cmd2

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.

Style Checker

Use doc8 to check the style of the documentation. This tool can be invoked using the proper options by typing:

$ invoke doc8