mirror of
https://github.com/kdave/btrfs-progs
synced 2025-01-01 19:22:05 +00:00
ab8dbea0dd
Fix the following warnings:
[SPHINX] man
../CHANGES:37: ERROR: Unexpected indentation.
../CHANGES:1183: WARNING: Block quote ends without a blank line; unexpected unindent.
./Documentation/DocConventions.rst:31: ERROR: Unexpected indentation.
./Documentation/Source-repositories.rst:2: WARNING: Duplicate explicit target name: "web access".
./Documentation/DocConventions.rst: WARNING: document isn't included in any toctree
The free format of CHANGES sometimes does not align with RST so fix it
so it's visually similar in both formats. Remove RST references to 'web
access', URLs are parsed and rendered clickable and we don't have full
reference list yet. Doc conventions have been updated to RST but not
finalized so put it to TODO section.
Signed-off-by: David Sterba <dsterba@suse.com>
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/
|