创建集合文档站点

antsibull-docs 可用于为单个集合创建文档站点。例如，请查看 根据 community.crypto 存储库的最新提交构建的 community.crypto 文档站点。本文档说明如何使用 antsibull-docs 构建此类文档站点，如何检查集合文档的代码风格，以及如何使用 GitHub Actions 自动化文档站点构建。

设置集合的开发环境

虽然 antsibull-docs 可以下载它应该为其生成文档的集合，但主要操作模式是使用可用于 ansible-core 的集合。

如果您只想创建文档，则必须安装 ansible-core、antsibull-docs 和您想要为其生成文档或验证文档的集合。要安装 ansible-core 和 antsibull-docs，您可以使用 Python venv。简而言之，如下所示：

$ python -m venv ~/antsibull-demo-venv
$ . ~/antsibull-demo-venv/bin/activate
$ python -m pip install ansible-core antsibull-docs

要安装集合，您可以使用 ansible-galaxy collection install，也可以在路径结构中提供集合存储库，以便 ansible-core 可以访问它们。如果您正在处理集合，则通常首选第二种方法。一种方法是为集合 <namespace>.<name> 创建一个目录结构 ansible_collections/<namespace>/<name>，并将 Ansible 的 ANSIBLE_COLLECTIONS_PATH 指向包含 ansible_collections 的目录。然后，您可以直接在 Ansible 中使用该集合。

例如，如果您想将集合树存储在 ~/collections/ 中，并且您想处理例如 community.crypto（存储在 ansible-collections/community.crypto GitHub 存储库 中），您可以按如下方式克隆它：

$ mkdir -p ~/collections/ansible_collections/community
$ export ANSIBLE_COLLECTIONS_PATH=~/collections
$ git clone git@github.com:ansible-collections/community.crypto.git ~/collections/ansible_collections/community/crypto

设置 ANSIBLE_COLLECTIONS_PATH 后，您可以直接使用集合中的模块和插件。

$ ansible localhost -m community.crypto.crypto_info
[WARNING]: No inventory was parsed, only implicit localhost is available
localhost | SUCCESS => {
    "changed": false,
    ...
}

在许多情况下，您希望克隆您的 fork 而不是集合的主存储库本身，并且只添加主存储库作为另一个远程存储库。请参阅您最喜欢的源代码管理工具/工作流程，了解如何设置环境。重要的是将集合检出到正确的路径结构中。

使用该路径结构，您还可以运行其他工具，例如 ansible-test。

$ cd ~/collections/ansible_collections/community/crypto
$ ansible-test sanity --docker -v

最后，您可以使用 ansible-doc 直接使用命令行查看插件、模块和角色文档。

# List modules and filter plugins:
$ ansible-doc --type module --list community.crypto
$ ansible-doc --type filter --list community.crypto

# Show documentation of modules and filters:
$ ansible-doc --type module community.crypto.crypto_info
$ ansible-doc --type filter community.crypto.gpg_fingerprint

antsibull-docs 在内部使用 ansible-doc 及其 JSON 输出提取集合文档。

集合文档代码风格检查

虽然 ansible-test 提供的 validate-modules 健全性测试 已经对模块和插件文档进行了一些验证，但它例如没有检查过滤器和测试插件，也没有检查对其他插件、模块和角色的交叉引用。antsibull-docs 提供了 lint-collection-docs 子命令，允许您对集合文档进行广泛验证，包括额外文档和集合级链接（请参见下面的相应部分）。基本用法如下：

$ cd ~/collections/ansible_collections/community/crypto
$ antsibull-docs lint-collection-docs --plugin-docs .

此子命令有多个选项，可用于控制验证。最重要的选项是：

• --plugin-docs：是否验证集合中包含的模块、插件和角色的模式和标记。默认情况下，不会运行此命令（为了向后兼容）。我们建议始终指定此选项。

• --validate-collection-refs {self,dependent,all}：指定如何验证插件/模块/角色文档中的插件/模块/角色间和集合间引用。这包括 Ansible 标记，如 M(foo.bar.baz) 或 O(foo.bar.baz#module:parameter=value)，以及其他链接，如 seealso 部分。如果设置为 self，则只验证对同一集合的引用。如果设置为 dependent，则只验证对集合本身及其（传递）依赖的集合的引用，包括对 ansible-core（作为 ansible.builtin）的引用。如果设置为 all，则验证对其他所有集合的引用。

  如果引用了未安装且在范围内的集合，则不会报告对它们的引用。可以通过指定 --disallow-unknown-collection-refs 来启用报告这些引用。

• --skip-rstcheck：默认情况下，当指定 --plugin-docs 时，antsibull-docs 会为模块/插件/角色文档生成 RST 文档并在其上运行 rstcheck。此步骤通常没有必要，因为它主要会指出 antsibull-docs 的 RST 生成代码中的错误，并且会降低大型集合的代码风格检查速度。

• --disallow-semantic-markup：如果您想避免 Ansible 标记中的语义标记，例如对于其文档必须能够使用旧版本的 ansible-doc 或 Automation Hub 正确呈现的集合，您可以使用此参数使 antsibull-docs 报告所有不受支持的标记。自 ansible-core 2.15.0 起支持语义标记。

通过运行以下命令可以实现最广泛的验证：

$ antsibull-docs lint-collection-docs --plugin-docs --skip-rstcheck \
                                      --validate-collection-refs=all \
                                      --disallow-unknown-collection-refs .

验证成功时，退出代码将为 0，否则将为非零值。如果为非零值，则验证错误将以 <filename>:<line>:<column>:<message> 的格式显示，如下所示：

plugins/modules/crypto_info.py:0:0: DOCUMENTATION -> description[2]: M(foo.bar.baz): a reference to the collection foo.bar is not allowed

这告诉您，在文件 plugins/modules/crypto_info.py 的 DOCUMENTATION 中，顶层 description 键的第二段中有一个损坏的引用 M(foo.bar.baz)。

ansible-test 也使用相同的输出格式。

构建文档站点

设置 Sphinx 文档站点的最简单方法是使用 antsibull-docs 的 sphinx-init 子命令：

# Create a subdirectory which should contain the docsite:
$ mkdir built-docs

# Create a Sphinx project for the collection community.crypto in there:
$ antsibull-docs sphinx-init --use-current --squash-hierarchy community.crypto --dest-dir built-docs

# Install requirements for the docsite build
# (if you don't have an active venv, create one!)
$ cd built-docs
$ python -m pip install -r requirements.txt

# Build the docsite by:
#  1. running antsibull-docs to create the RST files for the collection,
#  2. running Sphinx to compile everything to HTML
$ ./build.sh

# Open the built HTML docsite in a browser like Firefox:
$ firefox build/html/index.html

sphinx-init 子命令有很多配置选项：

• 如果您为单个集合构建了文档站点，最好像上面的示例一样指定 --squash-hierarchy。这避免了不必要的树结构。
• --use-current 控制是否应该假定集合已安装（如果指定了 --use-current），或者 antsibull-docs 是否应该临时自行安装它（如果没有指定 --use-current）。我们建议您自己安装集合并始终指定 --use-current。
• 您可以使用 --lenient（配置 Sphinx 不要过于严格）和 --fail-on-error（如果发生任何解析或模式验证错误，则失败而不是创建错误页面）来控制构建。在 CI 中使用 --fail-on-error 以确保尽早引发所有错误。在尝试成功构建文档站点时，--lenient 有助于避免 Sphinx 对错误过于严格。
• --index-rst-source 可用于将提供的文件复制到 rst/index.rst，而不是生成默认的 rst/index.rst 文件。
• --sphinx-theme 可用于选择不同的 Sphinx 主题。默认值为 sphinx-ansible-theme。
• --intersphinx 可用于添加 intersphinx 配置项，以允许使用 RST 引用更多外部文档。有关更多信息，请参阅 intersphinx 文档。
• --project、--copyright、--title、--html-short-title、--extra-conf、--extra-html-context 和 --extra-html-theme-options 可用于向 Sphinx 配置 conf.py 添加特定配置项。

配置文档站点

通常，配置使用 docs/docsite/config.yml YAML 文件完成。格式和选项如下：

---
# Whether the collection uses flatmapping to flatten subdirectories in
# `plugins/*/`.
flatmap: false

# List of environment variables that are defined by `.. envvar::` directives
# in the extra docsite RST files.
envvar_directives: []

# Changelog configuration (added in antsibull-docs 2.10.0)
changelog:
  # Whether to write the changelog (taken from changelogs/changelog.yaml, see the
  # antsibull-changelog documentation for more information) and link to it from the
  # collection's index page.
  write_changelog: false

大多数集合应该只使用 envvar_directives 和 changelog。flatmap 选项适用于旧版本的 community.general 和 community.network，应该只用于旧集合，不适用于新集合。

添加额外文档

可以将 RST 格式的额外文档添加到文档站点。这例如可用于提供场景指南。在 community.crypto 文档站点 上，例如，“场景指南”部分中有一些操作方法。

您需要在 docs/docsite/rst/ 中提供 RST 文件，并在 YAML 文件 docs/docsite/extra-docs.yml 中配置它们。例如，请参阅 community.crypto 的 extra-docs.yml，了解其工作原理。

---
sections:
  # We have one section labelled "Scenario Guides"
  - title: Scenario Guides
    toctree:
      # List the filenames in docs/docsite/rst without
      # the .rst extension here in the order you want
      # them to appear:
      - guide_selfsigned
      - guide_ownca

请注意，在 RST 文件中，您不能随意选择标签，而必须为每个标签添加前缀 ansible_collections.<namespace>.<name>.docsite.。这确保您不会意外地重复使用 Ansible 文档站点的其他部分使用的标签。对于 community.crypto，这可能如下所示：

.. _ansible_collections.community.crypto.docsite.guide_ownca:

How to create a small CA
========================

The `community.crypto collection
<https://galaxy.ansible.com/ui/repo/published/community/crypto/>`_
offers multiple modules that create private keys, certificate signing
requests, and certificates. This guide shows how to create your own
small CA and how to use it to sign certificates.

In all examples, we assume that the CA's private key is password
protected, where the password is provided in the
``secret_ca_passphrase`` variable.

Set up the CA
-------------

Any certificate can be used as a CA certificate. You can create a
self-signed certificate (see
:ref:`ansible_collections.community.crypto.docsite.guide_selfsigned`),
use another CA certificate to sign a new certificate (using the
instructions below for signing a certificate), ask (and pay) a
commercial CA to sign your CA certificate, etc.

...

如果您想引用模块、插件、角色、其选项和返回值，请参阅 Ansible 文档的样式指南。

向文档站点添加有用链接

您可以向您的集合页面和插件页面添加感兴趣的通用链接，例如指向如何提交错误报告、如何请求功能或在哪里寻求帮助的链接。您还可以提供指向通信渠道的链接，例如 Ansible 论坛、Matrix 房间、IRC 频道和邮件列表。

这些可以在 docs/docsite/links.yml 中配置。下面可以找到显示可用内容的模板：

---
# This will make sure that plugin and module documentation gets Edit on GitHub links
# that allow users to directly create a PR for this plugin or module in GitHub's UI.
# Remove this section if the collection repository is not on GitHub, or if you do not want this
# functionality for your collection.
edit_on_github:
  repository: ansible-collections/community.REPO_NAME
  branch: main
  # If your collection root (the directory containing galaxy.yml) does not coincide with your
  # repository's root, you have to specify the path to the collection root here. For example,
  # if the collection root is in a subdirectory ansible_collections/community/REPO_NAME
  # in your repository, you have to set path_prefix to 'ansible_collections/community/REPO_NAME'.
  path_prefix: ''

# Here you can add arbitrary extra links. Please keep the number of links down to a
# minimum! Also please keep the description short, since this will be the text put on
# a button.
#
# Also note that some links are automatically added from information in galaxy.yml.
# The following are automatically added:
#   1. A link to the issue tracker (if `issues` is specified);
#   2. A link to the homepage (if `homepage` is specified and does not equal the
#      `documentation` or `repository` link);
#   3. A link to the collection's repository (if `repository` is specified).

extra_links:
  - description: Report an issue
    url: https://github.com/ansible-collections/community.REPO_NAME/issues/new/choose

# Specify communication channels for your collection. We suggest to not specify more
# than one place for communication per communication tool to avoid confusion.
communication:
  forums:
    - topic: Ansible Forum
      # The following URL directly points to the "Get Help" section
      url: https://forum.ansible.com/c/help/6/none
  matrix_rooms:
    - topic: General usage and support questions
      room: '#users:ansible.im'
  irc_channels:
    # The IRC channels are only mentioned as examples and
    # should not be used except in very specific circumstances.
    - topic: General usage and support questions
      network: Libera
      channel: '#ansible'
  mailing_lists:
    # The mailing lists are only mentioned as examples and
    # should not be used except in very specific circumstances.
    # Please note that the ansible-project group used as an example
    # below is read-only and will soon vanish completely.
    - topic: Ansible Project List
      url: https://groups.google.com/g/ansible-project
      # You can also add a `subscribe` field with an URI that allows to subscribe
      # to the mailing list. For lists on https://groups.google.com/ a subscribe link is
      # automatically generated.

使用 GitHub Actions 发布文档站点

ansible-community/github-docs-build GitHub 存储库 提供可用于以下操作的动作和共享工作流程：

• 推送至 main 分支时构建集合文档站点，并将其上传到例如 GitHub Pages；
• 在 PR 期间构建集合文档站点，添加一个 PR 评论，显示与当前文档的差异，并可以选择将 PR 文档站点推送到 GitHub Pages，以便贡献者可以快速查看他们修改后的文档外观。

这些内容在代码库的 Wiki中进行了详细说明。请参考 Wiki 获取更多信息。

如果您想实际查看，可以看看 community.crypto 集合。

• 推送到 main 和 stable-* 分支时构建文档的工作流程
• PR 文档的工作流程

生成 RST 文件以包含在集合存储库中

一些集合在 docs/ 中包含了每个模块、插件和角色的 RST 文件。传统上，使用 ansible-network/collection_prep GitHub 存储库 中的 collection_prep_add_docs 来完成此操作，但该工具似乎已停止维护。

antsibull-docs 现在也可以使用 collection-plugins 子命令生成此类文件。操作方法如下：

$ cd ~/collections/ansible_collections/community/crypto
$ antsibull-docs collection-plugins --dest-dir docs/ --output-format simplified-rst --use-current --fqcn-plugin-names community.crypto

我不清楚为什么一些集合选择将其 RST 文件包含在它们的存储库中。我不建议这样做，而是提供一个渲染后的文档站点。如果用户只想使用已安装的集合来阅读文档，他们可以使用 ansible-doc 命令行工具，或者自己构建文档站点的 HTML 版本并在浏览器中查看，这样会有更好的体验。