Ansible 文档风格指南

欢迎来到 Ansible 风格指南！为了在 docs.ansible.com 上创建清晰、简洁、一致、有用的内容，请遵循以下准则

语言指南

我们希望 Ansible 文档能够

• clear

• direct

• 对话式

• 易于翻译

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

风格速查表

此速查表阐述了一些有助于实现“Ansible 风格”的规则

规则	范例	反例
使用主动语态	您可以通过以下方式运行任务	任务可以通过以下方式运行
使用现在时	此命令创建	此命令将创建
面向读者	当您扩展您的资产清单时	当托管节点数量增长时
使用标准英语	返回此页	跳回此页
使用美式英语	输出的颜色	输出的颜色

标题和节标题大小写

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

高级任务标题使用动名词（-ing 词），子任务标题使用祈使动词。例如，章节标题使用 Installing Ansible，其内部的步骤级标题使用 Install the package。

避免使用拉丁短语

像 e.g. 或 etc. 这样的拉丁词语和短语很容易被英语使用者理解。但对其他人来说可能较难理解，也给自动化翻译带来困难。

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

拉丁语	英语
i.e	换句话说
例如：	例如
等等	等等
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

• 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: 链接。长页面或具有多级标题的页面也可以包含本地目录。

注意

避免使用原始 URL。RST 和 Sphinx 允许 https://my.example.com，但这对于使用屏幕阅读器的人来说没有帮助。:ref: 链接会自动从锚点中获取标题，但对于外部链接，请始终使用 `链接标题 <链接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 模块可以通过 ansible.builtin.copy 进行链接”，以及“如果您想指定一个显式类型，请使用：copy 模块”。

除了 #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）。

添加本地目录

您正在阅读的页面包含一个本地目录。如果您包含本地目录

• 将其放置在主标题和（可选的）引言文本下方，而非上方

• 使用 :local: 指令，以便不包含页面的主标题

• 不要包含标题

语法如下

.. 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 中添加 alt 文本

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

在 md 中添加 alt 文本

![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 浏览器扩展 - 突出显示网页上的可访问性问题。

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

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

• 色盲滤镜 - 用于色盲测试。

更多资源

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

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

另请参阅

为 Ansible 文档做出贡献

如何为 Ansible 文档贡献

在本地测试文档

如何构建 Ansible 文档

交流方式

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