btrfs-progs/Documentation/DocConventions.rst

91 lines
3.3 KiB
ReStructuredText
Raw Normal View History

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/