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 模块可以链接到 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)。

添加本地 TOC

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

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

• 使用 :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 |

颜色和其他视觉信息

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

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

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

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

可访问性资源

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

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

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

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

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

更多资源

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

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

另请参阅

贡献 Ansible 文档

如何为 Ansible 文档做贡献

在本地测试文档

如何构建 Ansible 文档

沟通

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