为 Ansible 文档做贡献

Ansible 拥有大量的文档和一个小型编写团队。社区的支持有助于我们跟上新功能、修复程序和变更的步伐。

改进文档是为您对 Ansible 项目做出首次贡献的一种简便方法。您不必是程序员，因为我们的大部分文档都是用 YAML（模块文档）或 reStructuredText (rST) 编写的。一些集合层面的文档是用 Markdown 的一个子集编写的。如果您正在使用 Ansible，您已经在 Playbook 中使用过 YAML 了。rST 和 Markdown 大多只是纯文本。如果您使用 Edit on GitHub（在 GitHub 上编辑）选项，甚至不需要 Git 经验。

如果您在本文档网站上发现错别字、损坏的示例、缺失的主题，或任何其他错误或遗漏，请告知我们。以下是一些支持 Ansible 文档的方法：

直接在 GitHub 上编辑文档

对于错别字和其他快速修复，您可以直接在网站上编辑大部分文档。查看本页面右上角。该 Edit on GitHub 链接适用于文档中的所有指南页面。如果您有 GitHub 账户，可以通过这种方式轻松提交拉取请求 (Pull Request)。

注意

各个集合插件的源文件位于它们各自的存储库中。通过 Galaxy 上的链接找到集合的位置，以及关于如何为该集合做出贡献的任何指南。

要使用 Edit on GitHub 从 docs.ansible.com 提交文档 PR：

  1. 点击 Edit on GitHub。

  2. 如果您的 GitHub 账户中还没有 ansible 仓库的分支 (fork)，系统会提示您创建一个。

  3. 修正错别字、更新示例或进行您想做的任何其他更改。

  4. 在 GitHub 页面底部的 Propose file change（建议文件更改）标题下的第一个矩形中输入提交信息。越具体越好。例如：“修复 my_module 描述中的错别字”。如果愿意，您可以在第二个矩形中添加更多详细信息。保留那里的 +label: docsite_pr。

  5. 点击绿色的“Propose file change”按钮提交建议的更改。GitHub 会为您处理分支和提交，并打开一个标题为“Comparing Changes”的页面。

  6. 点击 Create pull request 以打开 PR 模板。

  7. 填写 PR 模板，尽可能包含与您的更改相关的详细信息。如果愿意，您可以更改 PR 的标题（默认与您的提交信息相同）。在 Issue Type 部分，删除除 Docs Pull Request 行以外的所有行。

  8. 通过点击 Create pull request 按钮提交您的更改。

  9. 请耐心等待 Ansibot（我们的自动化脚本）添加标签、通知文档维护者并启动 CI 测试运行。

  10. 密切关注您的 PR——文档团队可能会要求您进行更改。

审阅或解决待处理的问题

审阅或解决以下项目的待处理文档问题：

审阅待处理的 PR

审阅以下项目的待处理文档拉取请求：

要添加有益的审阅，请：

  • 如果适用，测试该更改。

  • 思考是否可以做得更好（包括措辞、结构、修复错别字等）。

  • 提出改进建议。

  • 使用 looks good to me（我看没问题）评论批准该更改。

开启新问题和/或 PR

如果您发现的问题太复杂，无法通过 Edit on GitHub 选项解决，且没有现有的待处理问题或 PR 记录该问题，请在正确的底层仓库中开启问题和/或 PR。对于大多数非插件或模块文档的页面，请使用 ansible/ansible-documentation。如果文档页面没有 Edit on GitHub 选项，请检查该页面是否为集合内的模块。如果是，请点击 Galaxy 上的集合链接，并选择右上角的 repo 按钮，以找到该集合和模块的源存储库。集合的 README 文件应包含有关如何为该集合做出贡献或报告问题的信息。

优秀的文档 GitHub 问题或 PR 应包含：

  • 明确的标题

  • 对问题的详细描述（即使是 PR 也需要——除非我们知道它要解决什么问题，否则很难评估建议的更改）

  • 其他信息的链接（相关问题/PR、外部文档、docs.ansible.com 上的页面等）

验证您的文档 PR

如果您对 Ansible 文档进行了多次更改，或添加了超过一行内容，请在开启拉取请求之前：

  1. 检查您的文本是否符合我们的 Ansible 文档风格指南。

  2. 测试您的更改是否存在 rST 错误。

  3. 在本地构建该页面，最好是构建整个文档站点。

注意

以下章节适用于源自 ansible/ansible-documentation 仓库的文档，不适用于来自单个集合的文档。有关如何为集合做出贡献的详细信息，请参阅集合的 README 文件。集合开发者也可以检查其集合级别的文档。请参阅 验证您的集合文档 获取详细信息。

设置本地构建文档的环境

要在本地构建文档，请确保您拥有一个可用的 开发环境。

要在本地机器上处理文档，您应该使用符合 ansible-core 最低要求的 Python 版本。有关最低 Python 版本的更多信息，请参阅 支持矩阵。

  1. 设置一个虚拟环境以安装依赖项。

    python3 -m venv ./venv
source ./venv/bin/activate

  2. 克隆构建文档所需的 Ansible Core 部分。

    python3 docs/bin/clone-core.py

  3. 安装未锁定或经过测试的文档依赖项。

    pip install -r tests/requirements.in -c tests/requirements.txt # Installs tested dependency versions.
pip install -r tests/requirements.in # Installs the unpinned dependency versions.

注意

检出 ansible/ansible-documentation 后，确保 docs/docsite/rst 目录具有足够严格的权限。它应该只对所有者账户可写。如果您的默认 umask 不是 022，您可以使用 chmod go-w docs/docsite/rst 在新分支中正确设置权限。或者，您可以将 umask 设置为 022，以使系统上所有新创建的文件（包括由 git clone 创建的文件）都具有正确的权限。

在本地测试文档

测试单个文件是否存在 rST 错误：

rstcheck changed_file.rst

在本地构建文档

构建文档是检查错误和审查更改的最佳方式。一旦 rstcheck 在没有错误的情况下运行，导航到 ansible-documentation/docs/docsite，然后构建您想要审查的页面。

注意

如果在安装 Python 3.8 或更高版本的 macOS 上进行构建，则必须使用 Sphinx >= 2.2.2。详情请参阅 #6803。

定期克隆 Ansible Core

ansible/ansible-documentation 仓库中的文档是基于 ansible/ansible 仓库构建的。当您设置本地构建环境时，您会克隆 Ansible Core 的相关部分。

为确保您使用 Ansible Core 的最新源代码，在构建文档之前，您应该定期运行以下脚本：

python3 docs/bin/clone-core.py

构建单个 rST 页面

使用 make 工具构建单个 rST 文件：

make htmlsingle rst=path/to/your_file.rst

例如

make htmlsingle rst=community/documentation_contributions.rst

此过程会编译所有链接，但提供的日志输出最少。如果您正在编写新页面或想要更详细的日志输出，请参考 使用 sphinx-build 构建 rST 文件 的说明。

注意

make htmlsingle 会在您在 rst= 中提供的路径开头添加 rst/，因此您无法使用自动补全输入文件名。如果操作不当，您将看到以下错误消息：

  • 如果您从 docs/docsite/rst/ 目录运行 make htmlsingle：make: *** No rule to make target `htmlsingle'. Stop.

  • 如果您从 docs/docsite/ 目录运行 make htmlsingle 并附带 rST 文档的完整路径：sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst']。

构建所有 rST 页面

构建所有几乎没有模块文档的 rST 文件：

make coredocs

这实际上构建的是 ansible-core 文档，而不是包含许多集合文档的 Ansible 社区包文档。

构建模块文档和 rST 页面

构建 Ansible 社区包的所有模块文档加上所有 rST 文件：

make webdocs

使用 sphinx-build 构建 rST 文件

高级用户可以直接使用 sphinx 工具构建一个或多个 rST 文件。如果您只构建单个页面，sphinx-build 会返回误导性的 undefined label（未定义的标签）警告，因为它不会创建内部链接。但是，sphinx-build 会返回更广泛的语法反馈，包括关于缩进错误和 x-string without end-string 的警告。这很有用，特别是如果您正在从头开始创建新页面。要使用 sphinx-build 构建页面：

sphinx-build [options] sourcedir outdir [filenames...]

您可以指定文件名，或使用 -a 构建所有文件，或两者都不指定以仅编译新的/更改的文件。

例如

sphinx-build -b html -c rst/ rst/dev_guide/ _build/html/dev_guide/ rst/dev_guide/developing_modules_documenting.rst

运行最终测试

当您提交文档拉取请求时，会运行自动化测试。这些相同的测试可以在本地运行。要这样做，请导航到存储库的顶级目录并运行：

make clean -C docs/docsite
python tests/checkers.py docs-build
python tests/checkers.py rstcheck

建议在干净的存储库副本上运行测试，这也是 make clean 命令的目的。

加入文档工作组

文档工作组 (DaWGs) 每周二在 Matrix 上的 docs:ansible.im 聊天室开会。欲了解更多信息（包括我们的议程链接），请访问我们的 论坛群组。

另请参阅

关于测试模块文档的更多信息

关于记录模块的更多信息