贡献 Ansible 文档

Ansible 拥有大量的文档，但编写人员团队规模较小。社区支持帮助我们跟上新功能、修复和更改。

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

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

直接在 GitHub 上编辑文档

对于错别字和其他快速修复，您可以直接从网站编辑大部分文档。查看此页面的右上角。Edit on GitHub 链接在文档中的所有指南页面上都可用。如果您有 GitHub 帐户，您可以通过这种方式提交快速简便的拉取请求。

注意

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

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

  1. 点击 Edit on GitHub。

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

  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（我们的自动化脚本）添加标签、ping 文档维护者并启动 CI 测试运行。

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

审查或解决未解决的问题

审查或解决 Ansible 项目的未解决的文档问题：

审查未合并的 PR

审查 Ansible 的未合并的文档拉取请求：

要添加有帮助的审查，请：

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

  • 考虑是否可以改进（包括措辞、结构、修复错别字等）。

  • 建议改进。

  • 使用 looks good to me 评论批准更改。

创建一个新的 issue 和/或 PR

如果您注意到的问题过于复杂，无法使用 Edit on GitHub 选项修复，并且没有未解决的问题或 PR 已经记录了该问题，请在正确的底层存储库上创建一个 issue 和/或 PR - 对于大多数不是插件或模块文档的页面，使用 ansible/ansible-documentation。如果文档页面没有 Edit on GitHub 选项，请检查该页面是否是集合中模块的页面。如果是，请点击 Galaxy 上集合的链接，然后点击右上角的 repo 按钮，查找该集合和模块的源存储库。集合自述文件应包含有关如何为该集合做出贡献或报告问题的信息。

一个优秀的文档 GitHub issue 或 PR 包括：

  • 具体的标题

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

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

验证您的文档 PR

如果您对 Ansible 文档进行了多处更改，或向其中添加了多于一行内容，请在打开拉取请求之前：

  1. 检查您的文本是否遵循我们的 Ansible 文档样式指南。

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

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

注意

以下部分适用于来自 ansible/ansible-documentation 存储库的文档，不适用于单个集合的文档。有关如何为该集合做出贡献的详细信息，请参阅集合自述文件。集合开发者还可以对他们的集合级文档进行 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，然后构建您要查看的页面。

注意

如果在使用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/目录使用rST文档的完整路径运行make htmlsingle：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)举行会议。有关更多信息，包括我们的议程链接，请访问我们的论坛小组。

另见

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

更多关于模块文档编制的信息