91 lines
3.3 KiB
ReStructuredText
91 lines
3.3 KiB
ReStructuredText
Conventions and style for documentation
|
|
---------------------------------------
|
|
|
|
Manual pages structure:
|
|
|
|
- add references to all external commands mentioned anywhere in the text to the *SEE ALSO* section
|
|
- add related, not explicitly mentioned commands or pages
|
|
- the heading levels are validated, underlined text by the following
|
|
|
|
- mandatory, manual page ``===``
|
|
- mandatory, sections ``---``
|
|
- optional, sub-sections ``^^^``
|
|
- optional, paragraphs ``"""``
|
|
|
|
- command-specific examples are mostly free of restrictions but should be
|
|
readable in all output formats (manual page, html)
|
|
|
|
- subcommands are in alphabetical order
|
|
|
|
- long command output or shell examples: verbatim output
|
|
- use ``..code-block::`` directive with ``bash`` or ``plain`` syntax hilighting
|
|
|
|
Quotes, reference, element formatting:
|
|
|
|
- exact syntax: monotype ````usage=0````
|
|
- reference to arguments: italics ``*italics*``
|
|
- command reference: bold text by directive ``:command:`btrfs filesystem show```
|
|
|
|
- subcommand names should be spelled in full, i.e. *filesystem* instead of *fi*
|
|
|
|
- file, directory or path references: by directive ``:file:`/path```
|
|
|
|
- section references without a label: italics ``*EXAMPLES*``
|
|
- section references with a target label: reference by directive ``:ref:<visible text`target-label`>``
|
|
|
|
- argument name in option description: caps in angle brackets ``<NAME>``
|
|
|
|
- reference in help text: caps ``NAME``
|
|
- also possible: caps italics ``*NAME*``
|
|
|
|
- command short description:
|
|
|
|
- command name: bold (not by directive) ``**command**``
|
|
- optional unspecified: brackets ``[options]``
|
|
- mandatory argument: angle brackets ``<path>``
|
|
- optional parameter with argument: ``[-p <path>]``
|
|
|
|
|
|
Referencing:
|
|
|
|
- add target labels for commands that are referenced and replace command name
|
|
with the reference target
|
|
|
|
- NOTE: we have either full doc reference by ``:doc:`docname``` or
|
|
inter-document reference to an **unambiguous** label
|
|
``:ref:`target-label```, i.e. we can't reference a label that may appear in
|
|
more files due to including, this will lead to the document itself that may
|
|
not be the full page (may be solvable by own directive, TBD)
|
|
|
|
- generic links can use the free form link syntax with description ```Link text <https://example.com>`_``
|
|
or plain link that will auto-render to a clikable link https://example.com
|
|
|
|
- in manual pages: always use full link as it's meant to be read in terminal
|
|
output and must allow copy&paste
|
|
|
|
- add more clickable references rather than less
|
|
|
|
Conventions:
|
|
|
|
- version should be formatted like ``6.1`` or ``v6.1`` and clear what
|
|
project/tool it's related to unless it's obvious from the context
|
|
|
|
|
|
Other:
|
|
|
|
- for notes use ``.. note::`` directive, is rendered as a separate paragraph and
|
|
should be used only for important information
|
|
|
|
- ``.. warning::`` directive is rendered as a separate paragraph
|
|
and most likely more visible than NOTE, use for critical information that
|
|
may cause harm, irreversible state or performance problems
|
|
|
|
- should point reader to other part of documentation to seek more details
|
|
|
|
|
|
References:
|
|
|
|
- RST https://www.sphinx-doc.org/en/master/
|
|
- RST and Sphinx Cheatsheet https://spl.hevs.io/spl-docs/writing/rst/cheatsheet.html
|
|
- RST Cheat Sheet https://sphinx-tutorial.readthedocs.io/cheatsheet/
|