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中添加替代文本：

.. 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浏览器扩展 - 突出显示网站页面上的辅助功能问题。

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

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

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

更多资源

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

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

另请参见：

贡献Ansible文档

如何贡献Ansible文档

本地测试文档

如何构建Ansible文档

沟通

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