Ansible 文档风格指南

欢迎来到 Ansible 风格指南！为了在 docs.ansible.com 上创建清晰、简洁、一致、实用的材料，请遵循以下指南。

语言指南

我们希望 Ansible 文档是

• 清晰的

• 直接的

• 对话式的

• 易于翻译的

我们希望阅读文档就像有一位经验丰富、友好的同事解释 Ansible 的工作原理。

风格速查表

这张速查表说明了几个有助于实现“Ansible 语调”的规则。

规则	好的例子	不好的例子
使用主动语态	你可以通过以下方式运行任务	任务可以通过以下方式运行
使用现在时	此命令创建	此命令将创建
直接与读者对话	当您扩展清单时	当管理节点数量增加时
使用标准英语	返回此页面	跳回此页面
使用美式英语	输出的颜色	输出的颜色

标题和标题大小写

标题应使用句子大小写。例如，本节的标题是 Title and heading case，而不是 Title and Heading Case 或 TITLE AND HEADING CASE。

避免使用拉丁短语

像 e.g. 或 etc. 这样的拉丁词语和短语很容易被英语使用者理解。它们可能难以被其他人理解，并且对于自动翻译也比较棘手。

使用以下英语术语代替拉丁语术语或缩写：

拉丁语	英语
i.e	换句话说
e.g.	例如
etc	等等
via	通过/通过
vs./versus	而不是/对抗

reStructuredText 指南

Ansible 文档是用 reStructuredText 编写的，并由 Sphinx 处理。我们遵循所有 rST 页面上的这些技术或机械指南。

标题符号

reStructuredText 中的节标题可以使用多种符号。Sphinx 在创建标题层次结构时会“边学边做”。为了使我们的文档易于阅读和编辑，我们遵循一组标准的标题符号。我们使用

• ### 带上横线，表示部分

###############
Developer guide
###############

• *** 带上横线，表示章节

*******************
Ansible style guide
*******************

• === 表示节

Mechanical guidelines
=====================

• --- 表示小节

Internal navigation
-------------------

• ^^^ 表示次小节

Adding anchors
^^^^^^^^^^^^^^

• """ 表示段落

Paragraph that needs a title
""""""""""""""""""""""""""""

语法高亮 - Pygments

Ansible 文档支持一系列 Pygments 词法分析器，用于 语法高亮，使我们的代码示例看起来更好。每个代码块都必须正确缩进，并用空行包围。

Ansible 文档允许以下值：

• none (不加亮)

• ansible-output (Ansible 输出的自定义词法分析器)

• bash

• console

• csharp

• ini

• json

• powershell

• python

• rst

• sh

• shell

• shell-session

• text

• yaml

• yaml+jinja

例如，您可以使用以下语法高亮 Python 代码：

.. code-block:: python

   def my_beautiful_python_code():
      pass

内部导航

锚点（也称为标签）和链接协同工作，帮助用户找到相关内容。本地目录表也有助于用户快速找到所需的信息。所有内部链接都应使用 :ref: 语法。每个页面至少应包含一个锚点，以支持内部 :ref: 链接。长页面或包含多个标题级别的页面还可以包含本地 TOC。

注意

避免使用原始 URL。RST 和 sphinx 允许 https://my.example.com，但这对于使用屏幕阅读器的用户来说没有帮助。 :ref: 链接会自动从锚点中获取标题，但对于外部链接，始终使用 `link title <link-url>`_ 格式。

添加锚点

• 在每个页面上至少包含一个锚点。

• 将主锚点放置在主标题上方。

• 如果文件有一个唯一的标题，请使用该标题作为主页面锚点。

.. _unique_page::

• 您也可以在页面的其他地方添加锚点。

添加内部链接

• 所有内部链接都必须使用 :ref: 语法。这些链接都指向上面定义的锚点。

:ref:`unique_page`
:ref:`this page <unique_page>`

第二个示例为链接添加了自定义文本。

添加指向模块和插件的链接

使用 :ansplugin: RST 角色，使用模块和插件的完全限定集合名称 (FQCN) 链接到它们。

The ansible.builtin.copy module can be linked with
:ansplugin:`ansible.builtin.copy#module`

If you want to specify an explicit type, use:
:ansplugin:`the copy module <ansible.builtin.copy#module>`

这将显示为“ansible.builtin.copy 模块可以通过以下方式链接” 和“如果要指定显式类型，请使用：copy 模块”。

您可以使用 #<plugin_type> 代替 #module，以引用类型为 <plugin_type> 的插件。

:ansplugin:`arista.eos.eos_config <arista.eos.eos_config#module>`
:ansplugin:`kubernetes.core.kubectl connection plugin <kubernetes.core.kubectl#connection>`
:ansplugin:`ansible.builtin.file lookup plugin <ansible.builtin.file#lookup>`

注意

ansible.builtin 是 ansible-core 中包含的模块的 FQCN。

添加指向模块和插件选项以及返回值的链接

使用 :ansopt: 和 :ansretval: 角色引用模块和插件的选项和返回值。

:ansopt:`ansible.builtin.file#module:path` references the ``path`` parameter of the
``ansible.builtin.file`` module; :ansopt:`ansible.builtin.file#module:path=/root/.ssh/known_hosts`
shows the assignment ``path=/root/.ssh/known_hosts`` as a clickable link.

:ansretval:`ansible.builtin.stat#module:stat.exists` references the ``stat.exists`` return value
of the ``ansible.builtin.stat`` module. You can also use ``=`` as for option values:
:ansretval:`ansible.builtin.stat#module:stat.exists=true` shows ``stat.exists=true``.

:ansopt:`foo` and :ansopt:`foo=bar` use the same markup for an option and an option
assignment without a link; the same is true for return values: :ansretval:`foo` and
:ansretval:`foo=bar`.

这将显示为“path 指的是 path 参数，该参数属于 ansible.builtin.file 模块；path=/root/.ssh/known_hosts 显示赋值 path=/root/.ssh/known_hosts 作为一个可点击的链接。” 和 “stat.exists 指的是 stat.exists 返回值，该返回值属于 ansible.builtin.stat 模块。 您也可以使用 = 来表示选项值：stat.exists=true 显示 stat.exists=true。” 和 “foo 和 foo=bar 使用相同的标记表示选项和选项赋值，但没有链接；返回值也是如此：foo 和 foo=bar。”.

对于选项和返回值，. 用于引用子选项和包含的返回值。 数组存根 ([...]) 可用于指示某些内容是列表，例如 :retval: 参数 ansible.builtin.service_facts#module:ansible_facts.services['systemd'].state 指的是 ansible_facts.services.state 返回值，该返回值属于 ansible.builtin.service_facts 模块 (ansible_facts.services['systemd'].state).

添加本地 TOC

您正在阅读的页面包含一个 本地 TOC。 如果你要包含一个本地 TOC

• 将其放置在主要标题和（可选）介绍性文本下方，而不是上方

• 使用 :local: 指令，这样页面的主要标题就不会包含在内

• 不要包含标题

语法如下：

.. contents::
   :local:

Markdown 指南

一些 Ansible 生态系统文档是用 markdown 编写的，并由 mkdocs 处理。 我们在所有 .md 页面上遵循以下技术或机械指南

标题符号

Markdown 中的节标题 可以使用多种符号。 为了使我们的文档易于阅读和编辑，我们遵循一组标准的标题符号。 我们使用

• # 用于页面标题

# Installation

• ## 用于节标题

## Installing on Linux

子节为每个子节添加一个额外的 #。 我们建议不要超过 ####，因为这表明文档嵌套过深，最好以多个页面呈现。

Markdown 中的链接

使用 Mkdocs，您可以使用本地文件的名称来格式化 内部链接 <https://mkdocs.pythonlang.cn/user-guide/writing-your-docs/#writing-with-markdown>`_，而不是外部 URL。

[configuration](/configuration)

您也可以直接链接到文件中的标题使用标题的小写形式。

[dependency](/configuration/#dependency)

外部链接使用类似的格式，带有外部 URL。

[Ansible Documentation](https://docs.ansible.org.cn)

代码块

Markdown 支持以下格式的代码块。

```text
docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md
```

无障碍指南

Ansible 文档的目标是更易于访问。 使用以下指南帮助我们实现这一目标。

图像和替代文本

确保所有图标、图像、图表和非文本元素都具有有意义的替代文本描述。 不要包含 CLI 输出的屏幕截图。 相反，使用代码块。

要在 rst 中添加替代文本

.. image:: path/networkdiag.png
   :width: 400
   :alt: SpiffyCorp network diagram

要在 md 中添加替代文本

![SpiffyCorp network diagram](path/networkdiag.png)

链接和超文本

URL 和交叉引用链接具有描述性文本，可以传达有关链接目标内容的信息。 请参阅 内部导航 了解如何在 RST 中格式化链接，并参阅 Markdown 中的链接 了解 Markdown。

表格

表格具有简单的逻辑阅读顺序，从左到右，从上到下。 表格包含标题行，并避免空或空白表格单元格。 使用描述性标题标记表格。

对于 RST

.. table:: File descriptions

  +----------+----------------------------+
  |File      |Purpose                     |
  +==========+============================+
  |foo.txt   |foo configuration settings  |
  +----------+----------------------------+
  |bar.txt   |bar configuration settings  |
  +----------+----------------------------+

对于 Markdown

#### File descriptions

  |File       |Purpose                     |
  |---------- | -------------------------- |
  |foo.txt    | foo configuration settings |
  |bar.txt    | bar configuration settings |

颜色和其他视觉信息

• 避免仅依赖感官特征的说明。 例如，不要使用 Click the square, blue button to continue.

• 通过方法而不是仅通过颜色来传达信息。

• 确保图像和图表中前景和背景文本或图形元素之间有足够的对比度。

• 导航界面的说明在没有方向指示器（如左、右、上、下）的情况下仍然有意义。

无障碍资源

使用以下资源来帮助测试您的文档更改

• axe DevTools 浏览器扩展 - 突出显示网站页面上的无障碍问题。

• WAVE 浏览器扩展 来自 WebAIM - 另一个无障碍测试器。

• Orca 屏幕阅读器 - 视力障碍人士常用的工具。

• 颜色过滤器 - 用于色盲测试。

更多资源

这些页面提供了有关文档的语法、风格和技术规则的更多帮助。

• 基本规则
• 语调风格
• 商标使用
• 语法和标点符号
• 拼写 - 用词 - 常用词和短语的使用和避免
• 首选术语
• 编写搜索可以找到的文档
• 资源

另请参阅

为 Ansible 文档做贡献

如何为 Ansible 文档做贡献

在本地测试文档

如何构建 Ansible 文档

沟通

有问题？ 需要帮助？ 想分享你的想法？ 请访问 Ansible 沟通指南