跳转至内容

创建集合文档站点

antsibull-docs 可用于为单个集合创建文档站点。例如，请查看 根据 community.crypto 仓库最新提交构建的 community.crypto 文档站点。本文档介绍了如何使用 antsibull-docs 构建此类文档站点，如何对集合文档进行 lint 检查，以及如何使用 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 输出格式来提取集合文档。

Linting（代码检查）集合文档

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

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

该子命令有多个选项，允许控制验证过程。最重要的选项如下：

  • --plugin-docs：是否验证集合中包含的模块、插件和角色的模式 (schema) 和标记 (markup)。默认情况下，不运行此检查（为了向后兼容）。我们建议始终指定此选项。
  • --check-extra-docs-refs：是否检查额外文档中使用的 :anscollection:、:ansplugin、:ansopt:、:ansoptref:、:ansretval:、:ansretvalref: 角色中的引用。

  • --validate-collection-refs {self,dependent,all}：指定如何验证插件/模块/角色文档（如果指定了 --plugin-docs）和额外文档（如果指定了 --check-extra-docs-refs）中的插件/模块/角色间引用以及集合间引用。这涵盖了 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 生成代码中的错误，并且会减慢 lint 检查的速度，特别是对于大型集合。

  • --disallow-semantic-markup：如果您想避免在 Ansible 标记中使用语义标记（例如，对于必须在旧版本 ansible-doc 或 Automation Hub 中渲染正常的集合文档），可以使用此参数让 antsibull-docs 报告所有不支持的标记。从 ansible-core 2.15.0 开始，ansible-doc 支持语义标记。

注意

在 antsibull-docs 3.0.0 中，上述部分选项的默认值将发生变化

  • --plugin-docs 将成为默认值；您需要指定 --no-plugin-docs 来不检查插件文档。
  • --check-extra-docs-refs 将成为默认值；您需要指定 --no-check-extra-docs-refs 来不检查额外文档引用。
  • --skip-rstcheck 将成为默认值；您需要指定 --no-skip-rstcheck 来检查生成的插件文档 RST 文件。

我们建议您现在就为您不想使用的功能显式提供 --no-XXX 变体（或者为了启用插件 RST 检查而显式提供 --no-skip-rstcheck）。这样，在 antsibull-docs 3.0.0 发布后，lint 命令的作用域就不会改变。

注意

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

$ antsibull-docs lint-collection-docs --plugin-docs --skip-rstcheck \
                                      --validate-collection-refs=all \
                                      --disallow-unknown-collection-refs \
                                      --check-extra-docs-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

# Configuration for 'antsibull-docs ansible-output'
# (See documentation for ansible-output for more information.)
ansible_output:
  # Insert definitions into 'env' for every ansible-output-data directive
  global_env:
    ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only
    ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 80

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

添加额外文档

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

您需要在 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 :anscollection:`community.crypto collection <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 文档的样式指南。

用于额外文档的特殊 RST 角色

Antsibull-docs 提供了多种角色来引用 Ansible 内容，而无需手动组合正确的 RST 引用标签。

  • :ansval:：格式化值。

    语法如下

    :ansval:`some value`

  • :ansopt:：格式化选项名称；引用模块、插件或角色的选项。

    语法如下

    An option with an optional value, without reference:
:ansopt:`option_name`
:ansopt:`option_name=value`

An option with an option value, referencing an option of a plugin
(specified by its FQCN) and plugin type (module, lookup, filter, ...):
:ansopt:`namespace.name.plugin_name#plugin_type:option_name`
:ansopt:`namespace.name.plugin_name#plugin_type:option_name=value`

For roles (plugin type "role"), you also have to specify the entrypoint
(usually "main"):
:ansopt:`namespace.name.role_name#role:entrypoint:option_name`
:ansopt:`namespace.name.role_name#role:entrypoint:option_name=value`

Suboptions must be referenced by separating the different levels by dot:
:ansopt:`namespace.name.plugin#type:option.suboption.subsuboption=foo`

You can use "[]" (with possible content) to indicate lists:
:ansopt:`namespace.name.plugin#type:option[].suboption[n-1].subsuboption["key"]=foo`

  • :ansretval:：格式化返回值；引用模块或插件的返回值。

    基本上语法与 :ansopt: 相同，只是它引用的是返回值而不是选项。

  • :ansoptref:：引用模块、插件或角色的选项。

    语法如下

    An option with an option value, referencing an option of a plugin
(specified by its FQCN) and plugin type (module, lookup, filter, ...):
:ansoptref:`Title <namespace.name.plugin_name#plugin_type:option_name>`

For roles (plugin type "role"), you also have to specify the entrypoint
(usually "main"):
:ansoptref:`Title <namespace.name.role_name#role:entrypoint:option_name>`

Suboptions must be referenced by separating the different levels by dot:
:ansoptref:`Title <namespace.name.plugin#type:option.suboption.subsuboption=foo>`

You can use "[]" (with possible content) to indicate lists
(these are ignored and not shown anywhere):
:ansoptref:`Title <namespace.name.plugin#type:option[].suboption[n-1].subsuboption["key"]>`

  • :ansretvalref:：格式化返回值；引用模块或插件的返回值。

    基本上语法与 :ansoptref: 相同，只是它引用的是返回值而不是选项。

  • :ansenvvar:：格式化带有赋值可能的环境变量。

    语法如下

    Environment variable with optional value:
:ansenvvar:`FOO`
:ansenvvar:`FOO=bar`

  • :ansenvvarref:：格式化带有赋值可能的环境变量；引用该环境变量。

    语法如下

    Environment variable with optional value:
:ansenvvarref:`FOO`
:ansenvvarref:`FOO=bar`

A reference to the definition of "FOO" is added.

  • :ansplugin:：引用插件、模块或角色/角色入口点。

    语法如下

    Reference a plugin of a given type in a collection, with an optional title:
:ansplugin:`namespace.name.plugin_name#plugin_type`
:ansplugin:`Reference title <namespace.name.plugin_name#plugin_type>`

For roles, you can also specify an entrypoint:
:ansplugin:`namespace.name.role_name#role:entrypoint`
:ansplugin:`Reference title <namespace.name.role_name#role:entrypoint>`

  • :anscollection:：引用集合，或集合的特定部分/页面。

    语法如下

    Reference the collection's page:
:anscollection:`namespace.name`
:anscollection:`namespace.name#collection`
:anscollection:`namespace.name#plugins`

Reference the communication section on the collection's page:
:anscollection:`namespace.name#communication`

Reference the collection's changelog:
:anscollection:`namespace.name#changelog`
Reference the changelog section on the collection's page:
:anscollection:`namespace.name#changelog-section`

Reference the plugin index on the collection's page:
:anscollection:`namespace.name#plugin-index`

Reference the list of plugins of a given type on the collection's page:
:anscollection:`namespace.name#plugin-<type>`
Concretely:
:anscollection:`namespace.name#plugin-module`
:anscollection:`namespace.name#plugin-lookup`
:anscollection:`namespace.name#plugin-role`

您可以将感兴趣的通用链接添加到您的集合页面和插件页面，例如指向如何提交错误报告、如何请求功能或何处寻求帮助的链接。您还可以提供指向交流渠道的链接，如 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 仓库 提供了可用于以下操作的 Actions 和共享工作流

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

这些内容在 仓库的 Wiki 中有详细记录。请参阅 Wiki 以获取更多信息。

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

生成用于包含在集合仓库中的 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 版本并在浏览器中查看，会有更好的体验。