1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
Documentation Conventions
=========================
Guiding Principles
------------------
Follow the `Documentation Principles
<http://www.writethedocs.org/guide/writing/docs-principles/>`_ described by
`Write The Docs <http://www.writethedocs.org>`_
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
------------------------------
Hyperlinks
----------
If you want to use an external hyperlink target, define the target at the top of the page,
not the bottom.
We use the Sphinx `autosectionlabel <http://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html>`_ extension. This allows you to reference any header in any document
by::
See :ref:`features/argument_processing:Help Messages`
or ::
See :ref:`custom title<features/argument_processing:Help Messages>`
Which render like
See :ref:`features/argument_processing:Help Messages`
and
See :ref:`custom title<features/argument_processing:Help Messages>`
Autolinking
-----------
Referencing cmd2 API documentation
----------------------------------
Info and Warning Callouts
-------------------------
Wrapping
--------
Hard wrap all text with line lengths less than 80 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.
|
