Ansible 文档风格指南

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

语言准则

我们希望 Ansible 文档是

• 清晰的

• 直接的

• 对话式的

• 易于翻译的

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

风格速查表

此速查表说明了一些有助于实现“Ansible 基调”的规则

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

标题和标题大小写

标题和标题应使用句子大小写。例如，本节的标题是 标题 和 标题 大小写，而不是 标题 和 标题 大小写 或 标题 和 标题 大小写。

避免使用拉丁语短语

英语使用者很容易理解像 例如 或 等等 这样的拉丁语单词和短语。对于其他人来说，它们可能更难理解，而且对于自动翻译也很棘手。

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

拉丁语	英语
即	换句话说
例如	例如
等等	等等
通过	通过/通过
与/对比	而不是/反对

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

• 控制台

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

注意

避免使用原始 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>`

这显示为“可以使用 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: 角色引用模块和插件的选项和返回值

: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” 指的是 ansible.builtin.file 模块的 path 参数；path=/root/.ssh/known_hosts 显示赋值 path=/root/.ssh/known_hosts 为一个可点击的链接。” 以及 “stat.exists” 指的是 ansible.builtin.stat 模块的 stat.exists 返回值。您也可以使用 = 作为选项值：stat.exists=true 显示 stat.exists=true。”以及 “foo” 和 “foo=bar” 使用相同的标记来表示没有链接的选项和选项赋值；返回值也是如此：“foo” 和 “foo=bar”。

对于选项和返回值，. 用于引用子选项和包含的返回值。数组存根 ([...]) 可用于指示某项是列表，例如 :retval: 参数 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.pythonlang.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 |

颜色和其他视觉信息

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

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

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

• 在没有方向指示（例如左、右、上和下）的情况下，用于浏览界面的说明应该有意义。

辅助功能资源

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

• axe DevTools 浏览器扩展程序 - 突出显示网站页面上的辅助功能问题。

• WebAIM 的 WAVE 浏览器扩展程序 - 另一个辅助功能测试器。

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

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

更多资源

这些页面为文档的语法、文体和技术规则提供了更多帮助。

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

另请参阅

为 Ansible 文档做出贡献

如何为 Ansible 文档做出贡献

在本地测试文档

如何构建 Ansible 文档

交流

有问题吗？需要帮助吗？想分享您的想法吗？请访问 Ansible 交流指南