Skip to content

Latest commit

 

History

History
106 lines (69 loc) · 3.96 KB

DocConventions.rst

File metadata and controls

106 lines (69 loc) · 3.96 KB

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 highlighting

Quotes, reference, element formatting:

  • exact syntax: monotype ``usage=0``
  • reference to arguments: italics *italics*
  • command reference:
    • any system command, example, bold text by directive :command:`btrfs filesystem show`
    • subcommands with their own manual page :doc:`btrfs-filesystem`
    • 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. this 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
  • ambiguous or duplicate labels (that exist in a file that is included from other documents) need to be
    • defined as .. duplabel:: labelname
    • referenced as :docref:`visible text <document:label>`
  • generic links can use the free form link syntax with description `Link text <https://example.com>`__ (note the double underscore, this is anonymous link and does not create a reference) or plain link that will auto-render to a clickable 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
  • own manual page references:
    • :doc:`btrfs-filesystem`, i.e. it's the document name, it will render the section automatically
    • other manual pages :manref:page(1), the exact name and section number
  • add more clickable references rather than less
  • custom rules and directives are implemented in :file:`Documentation/conf.py`

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: