btrfs-progs: docs: update doc style and conventions
Issue: #638 Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
parent
bb0ca35245
commit
4790665142
|
@ -3,49 +3,88 @@ Conventions and style for documentation
|
|||
|
||||
Manual pages structure:
|
||||
|
||||
- add references to all external commands mentioned anywhere in the text to the
|
||||
*SEE ALSO* section
|
||||
- also add related, not explicitly mentioned
|
||||
- the heading levels are validated
|
||||
- mandatory, manual page ===
|
||||
- mandatory, sections ---
|
||||
- optional, sub-sections ^^^
|
||||
- command-specific examples are mostly free of restrictions but should be
|
||||
readable in all output formats (manual page, html)
|
||||
- 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
|
||||
|
||||
- subcommands are in alphabetical order
|
||||
- mandatory, manual page ``===``
|
||||
- mandatory, sections ``---``
|
||||
- optional, sub-sections ``^^^``
|
||||
- optional, paragraphs ``"""``
|
||||
|
||||
- long command output or shell examples: verbatim output
|
||||
- use code-block:: directive
|
||||
- command-specific examples are mostly free of restrictions but should be
|
||||
readable in all output formats (manual page, html)
|
||||
|
||||
Quotation in subcommands:
|
||||
- subcommands are in alphabetical order
|
||||
|
||||
- exact syntax: monotype ``usage=0``
|
||||
- reference to arguments etc: *italics*
|
||||
- command reference: bold ``btrfs filesystem show``
|
||||
- subcommand names should be spelled in full, i.e. *filesystem* instead of *fi*
|
||||
- section references: italics *EXAMPLES*
|
||||
- long command output or shell examples: verbatim output
|
||||
- use ``..code-block::`` directive with ``bash`` or ``plain`` syntax hilighting
|
||||
|
||||
- argument name in option description: caps in angle brackets <NAME>
|
||||
- reference in help text: caps NAME
|
||||
- also possible: caps italics *NAME*
|
||||
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
|
||||
|
||||
- command short description:
|
||||
- command name: bold **command**
|
||||
- optional unspecified: brackets [options]
|
||||
- mandatory argument: angle brackets <path>
|
||||
- optional parameter with argument: [-p <path>]
|
||||
|
||||
Other:
|
||||
|
||||
- for notes use note:: directive, is rendered as a separate paragraph and
|
||||
should be used only for important information
|
||||
- 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
|
||||
|
||||
- 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 and Sphinx Cheatsheet https://spl.hevs.io/spl-docs/writing/rst/cheatsheet.html
|
||||
- RST Cheat Sheet https://sphinx-tutorial.readthedocs.io/cheatsheet/
|
||||
|
||||
- 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/
|
||||
|
|
Loading…
Reference in a new issue