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)
    特定于命令的示例大多没有限制，但应在所有输出格式（手册页、html）中可读

  • subcommands are in alphabetical order
    子命令按字母顺序排列

  • long command output or shell examples: verbatim output - use ..code-block:: directive with bash or plain syntax hilighting
    长命令输出或 shell 示例：直接输出 - 使用 ..code-block:: 指令与 bash 或 plain 语法高亮显示

Quotes, reference, element formatting:
引用、参考、元素格式化：

  • exact syntax: monotype ``usage=0``
    精确语法：等宽字体 ``usage=0``

  • reference to arguments: italics *italics*
    参数引用：斜体 *italics*

  • command reference: bold text by directive :command:`btrfs filesystem show`
    命令引用：通过指令加粗文本 :command:`btrfs filesystem show`

    • subcommand names should be spelled in full, i.e. filesystem instead of fi
      子命令名称应全拼写，例如 filesystem 而不是 fi

  • file, directory or path references: by directive :file:`/path`
    文件、目录或路径引用：通过指令 :file:`/path`

  • section references without a label: italics *EXAMPLES*
    没有标签的章节引用：斜体 *EXAMPLES*

  • section references with a target label: reference by directive :ref:<visible text`target-label`>
    带有目标标签的章节引用：通过指令引用 :ref:<visible text`target-label`>

  • argument name in option description: caps in angle brackets <NAME>
    选项描述中的参数名称：尖括号中的大写字母 <NAME>

    • reference in help text: caps NAME
      帮助文本中的参考：大写字母 NAME

    • also possible: caps italics *NAME*
      也可能是：大写字母斜体 *NAME*

  • command short description:
    命令简短描述：

    • command name: bold (not by directive) **command**
      命令名称：加粗（非指令） **command**

    • optional unspecified: brackets [options]
      可选未指定：括号 [options]

    • mandatory argument: angle brackets <path>
      必填参数：尖括号 <path>

    • optional parameter with argument: [-p <path>]
      带参数的可选参数： [-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)
    注意：我们要么通过 :doc:`docname` 进行完整文档引用，要么通过对一个明确标签的文档间引用 :ref:`target-label` ，即我们不能引用可能出现在多个文件中的标签，因为包含这将导致文档本身可能不是完整页面（可能可以通过自己的指令解决，待定）

  • 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
    通用链接可以使用自由形式的链接语法与描述 `Link text <https://example.com>`_ 或自动呈现为可点击链接的纯链接 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
    版本应该格式化为 6.1 或 v6.1 ，并清楚地说明它与哪个项目/工具相关，除非从上下文中很明显

Other: 其他：

  • for notes use .. note:: directive, is rendered as a separate paragraph and should be used only for important information
    对于注释，请使用 .. note:: 指令，它被呈现为单独的段落，应仅用于重要信息

  • .. 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
    .. warning:: 指令被呈现为单独的段落，很可能比注意更显眼，用于可能导致危害、不可逆状态或性能问题的关键信息

    • should point reader to other part of documentation to seek more details
      应该引导读者查阅文档的其他部分以获取更多细节

References: 参考资料：