为 Ansible 文档做贡献

Ansible 有大量的文档，但只有一个小的编写团队。社区的支持帮助我们跟上新功能、修复和变更。

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

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

直接在 GitHub 上编辑文档

对于错别字和其他快速修复，您可以直接从站点编辑大多数文档。查看此页面的右上角。在文档中的所有指南页面上都提供了 在 GitHub 上编辑 链接。如果您有 GitHub 帐户，则可以通过这种方式提交快速简单的 pull request。

注意

各个集合插件的源文件存在于各自的存储库中。请按照 Galaxy 上的集合链接查找存储库的位置以及有关如何为该集合做出贡献的任何指南。

要从 docs.ansible.com 使用 在 GitHub 上编辑 提交文档 PR

  1. 单击 在 GitHub 上编辑。

  2. 如果您的 GitHub 帐户上还没有 ansible 存储库的分支，系统会提示您创建一个分支。

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

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

  5. 单击绿色的“建议文件更改”按钮提交建议的更改。GitHub 将为您处理分支和提交，并打开一个标题为“比较更改”的页面。

  6. 单击 创建 pull request 以打开 PR 模板。

  7. 填写 PR 模板，包括尽可能多的详细信息。您可以根据需要更改 PR 的标题（默认情况下与您的提交消息相同）。在 问题 类型 部分，删除除 文档 Pull 请求 行之外的所有行。

  8. 单击 创建 pull request 按钮提交您的更改。

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

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

审查或解决开放的问题

审查或解决以下问题的开放文档问题

审查开放的 PR

审查以下内容的开放文档 pull request

要添加有用的评论，请

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

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

  • 提出改进建议。

  • 使用 看起来 不错 我 同意 注释批准更改。

开启新的问题和/或 PR

如果您发现的问题太复杂，无法使用 在 GitHub 上编辑 选项进行修复，并且没有开放的问题或 PR 已经记录了该问题，请在正确的底层存储库上打开一个问题和/或 PR - 对于大多数不是插件或模块文档的页面，请使用 ansible/ansible-documentation。如果文档页面没有 在 GitHub 上编辑 选项，请检查该页面是否是集合中的模块。如果是，请点击 Galaxy 上的集合链接，然后选择右上角的 repo 按钮，查找该集合和模块的源存储库。集合的 README 文件应包含有关如何为该集合做出贡献或报告问题的信息。

一个出色的文档 GitHub 问题或 PR 包括

  • 一个具体的标题

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

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

验证你的文档 PR

如果您对 Ansible 文档进行了多次更改，或者添加了超过一行，请在打开 pull request 之前

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

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

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

注意

以下部分适用于来自 ansible/ansible-documentation 仓库的文档，不适用于来自个别集合的文档。有关如何为集合贡献内容的详细信息，请参阅集合的 README 文件。集合开发人员也可以对他们的集合级文档进行 lint 检查。有关详细信息，请参阅 验证你的集合文档。

设置本地构建文档的环境

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

要在本地计算机上使用文档，你应该使用满足 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.
pip install -r tests/requirements-relaxed.in # Installs the unpinned dependency versions including untested antsibull-docs.

注意

检出 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，然后构建你要查看的页面。

注意

如果在 macOS 上使用 Python 3.8 或更高版本进行构建，则必须使用 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) 每周二在 docs:ansible.im 聊天室 (Matrix 上) 举行会议。有关更多信息，包括指向我们议程的链接，请访问我们的论坛小组。

另请参阅

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

有关记录模块的更多信息