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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
Documentation style guide
*************************
Language
--------
Where possible, text should be written in US English. However, discretion and
common sense can both be applied.
Try to be concise and to the point in your writing. It is acceptable to link
to official documentation elsewhere rather than repeating content. It's also
good practice not to assume that your reader has the same level of knowledge
as you, so if you're covering a new or complicated topic, then providing
contextual links to help the reader is encouraged.
Feel free to include a "Further reading" section at the end of a page if you
have additional resources an interested reader might find helpful.
Headings
--------
In reStructuredText, headings are denoted using symbols to underline the text.
The headings used across the documentation use the following hierarchy, which
is borrowed from the `Python style guide`_:
- ``#####``: Top level header (reserved for the main index page)
- ``*****``: Title header (used once at the top of a new page)
- ``=====``: Section headers
- ``-----``: Subsection headers
- ``^^^^^``: Sub-subsection headers
- ``"""""``: Paragraphs
The length of the underline must be at least as long as the title itself.
Ensure that you do not skip header levels when creating your document
structure, i.e., that a section is followed by a subsection, and not a
sub-subsection.
Line length
-----------
Please keep the line lengths to a maximum of **79** characters. This ensures
that the pages and tables do not get so wide that side scrolling is required.
Blank spaces at the ends of lines must also be removed, otherwise the `tox`
build checks will fail (it will warn you about trailing whitespace).
Anchor labels
-------------
Adding an anchor label at the top of the page allows for the page to be
referenced by other pages. For example for the FAQ page this would be:
.. code-block:: rst
.. _faq:
FAQ
***
When the reference is used in a document, the displayed text will be that of
the next heading immediately following the label (so, FAQ in this example),
unless specifically overridden.
If you use labels within a page to refer, for example, to a subsection, use a
label that follows the format: ``[pagelabel]-[Section]`` e.g., for this
"Anchor labels" section, something like ``_docs-Anchor:`` or ``_docs-Label:``.
Using a consistent style will aid greatly when referencing from other pages.
Links
-----
To aid in documentation maintenance and keeping links up-to-date, links should
be presented in a single block at the end of the page.
Where possible, use contextual text in your links to aid users with screen
readers and other accessibility tools. For example, "check out our
:ref:`documentation style guide<docs>`" is preferable to "click
:ref:`here<docs>` for more".
Images
------
It is generally best to avoid screenshots where possible. If you need to refer
to text output, you can use code blocks. For diagrams, we recommend the use of
`Mermaid`_.
File names
----------
File names should be decorated with backticks to ensure monospace font is used
to distinguish the name from regular text.
Code blocks
-----------
Our documentation uses the Sphinx extension ``sphinx-copybutton``, which
creates a small button on the right-hand side of code blocks for users to copy
the code snippets we provide.
The copied code will strip out the prompt symbol (``$``) so that users can
paste commands directly into their terminal. For user convenience, please
ensure that code output is presented in a separate code block to the commands.
Vertical whitespace
-------------------
One newline between each section helps ensure readability of the documentation
source code.
Acronyms
--------
Acronyms are always capitalized (e.g., JSON, YAML, QEMU, LXD) in text.
The first time an acronym is used on a page, it is best practice to introduce
it by showing the expanded name followed by the acronym in parentheses. E.g.,
Quick EMUlator (QEMU). If the acronym is very common, or you provide a link to
a documentation page that provides such details, you will not need to do this.
Common terms
------------
The following project terms should follow specific usage in text:
- **cloud-init**: Always hyphenated, and follows sentence case, so only
capitalized at the start of a sentence.
- **datasource**: One word.
- **user-data**: Two words, always hyphenated.
- **vendor-data**: Two words, always hyphenated.
- **cloud-config**: Two words, always hyphenated.
- **instance-data**: Two words, always hyphenated.
- **meta-data**: Two words, always hyphenated.
.. _Read the Docs: https://readthedocs.com/
.. _Python style guide: https://devguide.python.org/documentation/markup/
.. _Mermaid: https://mermaid.js.org/
|
