52 lines
1.8 KiB
ReStructuredText
52 lines
1.8 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
|
|
- 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)
|
|
|
|
- subcommands are in alphabetical order
|
|
|
|
- long command output or shell examples: verbatim output
|
|
- use code-block:: directive
|
|
|
|
Quotation in subcommands:
|
|
|
|
- exact syntax: monotype ``usage=0``
|
|
- reference to arguments etc: *italics*
|
|
- command reference: bold ``btrfs filesystem show``
|
|
- subcommand names should be spelled in full, ie. *filesystem* instead of *fi*
|
|
- section references: italics *EXAMPLES*
|
|
|
|
- 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 **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
|
|
|
|
- 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/
|