Ansible 文档风格指南

欢迎阅读 Ansible 风格指南！为了在 docs.ansible.com 上创建清晰、简洁、一致且有用的材料，请遵循这些准则

语言准则

我们希望 Ansible 文档是

• clear

• direct

• 对话式的

• 易于翻译的

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

风格备忘录

此备忘录说明了一些有助于实现“Ansible 语调”的规则

规则	好的示例	差的示例
使用主动语态	你可以通过以下方式运行任务	任务可以通过以下方式运行
使用现在时	此命令创建一个	此命令将创建一个
称呼读者	当你扩展你的清单 (inventory) 时	当受控节点的数量增加时
使用标准英语	返回此页面	跳回此页面
使用美式英语	输出的颜色 (color)	输出的颜色 (colour)

标题和标题栏大小写

标题和标题栏应按句首大写（sentence case）书写。例如，本节的标题是 Title and heading case，而不是 Title and Heading Case 或 TITLE AND HEADING CASE。

对高级别任务标题使用动名词（-ing 单词），对子任务标题使用祈使句动词。例如，章标题使用 Installing Ansible，其中的步骤级标题使用 Install the package。

避免使用拉丁短语

拉丁单词和短语（如 e.g. 或 etc.）很容易被英语母语者理解。但对于其他人来说可能较难理解，且不利于机器自动翻译。

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

拉丁语	英语
i.e	in other words
例如：	例如
等等	and so on
via	by/ through
vs./versus	rather than/against

reStructuredText 准则

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

标题符号

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

• ### 带有上划线，用于 Parts

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

• *** 带有上划线，用于 Chapters

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

• === 用于 Sections

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

• --- 用于 Subsections

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

• ^^^ 用于 Sub-subsections

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

• """ 用于 Paragraphs

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

语法高亮 - Pygments

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

Ansible 文档允许以下值

• none（无高亮）

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

• bash

• console

• csharp

• diff

• ini

• jinja

• json

• md

• 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-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>`

这显示为“The ansible.builtin.copy module can be linked with ansible.builtin.copy”和“If you want to specify an explicit type, use: the copy module”。

除了 #module，你还可以指定 #<plugin_type> 来引用类型为 <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: 角色引用模块和插件的选项和返回值，同时显示选项或返回值的名称以及（可选）一个值。使用 :ansoptref: 和 :ansretvalref: 角色在显示提供的标题时引用模块和插件的选项和返回值。

以下示例显示了它们的用法

: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.

You can :ansoptref:`provide a path <ansible.builtin.file#module:path>`
to the :ansplugin:`ansible.builtin.file#module`; its value is
:ansretvalref:`returned as a return value <ansible.builtin.file#module:path>`.

: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 引用 ansible.builtin.file 模块的 path 参数；path=/root/.ssh/known_hosts 将赋值 path=/root/.ssh/known_hosts 显示为一个可点击的链接。

你可以向 ansible.builtin.file 提供一个路径；其值作为返回值返回。

stat.exists 引用 ansible.builtin.stat 模块的 stat.exists 返回值。你也可以像对选项值那样使用 =：stat.exists=true 显示 stat.exists=true。

foo 和 foo=bar 为没有链接的选项和选项赋值使用相同的标记；返回值也是如此：foo 和 foo=bar。

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

添加本地 TOC

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

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

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

• 不要包含标题 (title)

语法如下

.. contents::
   :local:

Markdown 准则

一些 Ansible 生态文档是用 markdown 编写并由 mkdocs 处理的。我们在所有 .md 页面上遵循这些技术或机械准则

标题符号

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

• # 用于页面标题

# Installation

• ## 用于章节标题

## Installing on Linux

子章节每层增加一个 #。我们建议不要超过 ####，因为这表明文档嵌套过深，最好分拆为多个页面。

在 Markdown 中添加链接

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

[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 |

颜色和其他视觉信息

• 避免仅依赖感官特征的指令。例如，不要使用 点击正方形的蓝色按钮以继续。

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

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

• 界面导航指令在没有左、右、上、下等方向指示符的情况下也应有意义。

可访问性资源

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

• axe DevTools 浏览器扩展 - 高亮显示网站页面上的可访问性问题。

• WebAIM 的 WAVE 浏览器扩展 - 另一个可访问性测试工具。

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

• 颜色过滤器 (color filter) - 用于色盲测试。

更多资源

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

• 基本规则
• 语气风格
• 商标使用
• 语法与标点
• 拼写 - 词汇使用 - 应使用和应避免的常用词汇与短语
• 首选术语
• 编写可被搜索到的文档
• 资源

另请参阅

为 Ansible 文档做出贡献

如何向 Ansible 文档做贡献

在本地测试文档

如何构建 Ansible 文档

交流方式

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