- 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
- 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
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 other code, like shell commands, then use
Referencing cmd2 API documentation¶
Info and Warning Callouts¶
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.
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.