antsibull-docs – 构建 Ansible 文档¶
本软件包提供了用于验证和构建 Ansible 文档的工具。它主要由一个 CLI 工具 antsibull-docs 和一个 Sphinx 扩展组成。主要输出格式是供 Sphinx 使用的 reStructured Text (RST) 文件。
Collection 维护者和作者应参考本文档站的 创建 collection 文档站 章节。
antsibull-docs 遵循 Ansible 行为准则。
注意
需要帮助或想讨论本项目？请参阅我们的 社区指南 了解如何参与讨论！
antsibull-docs 子命令¶
主要的 CLI 工具 antsibull-docs 具有多个子命令
devel和stable子命令用于构建位于 docs.ansible.com/projects/ansible/devel 和 docs.ansible.com/projects/ansible/latest 的官方 Ansible 文档站。current和collection子命令用于为单个 collection 构建文档站。plugin和collection-plugins子命令用于渲染单个（或所有）插件、模块或角色的文档。lint-collection-docs和lint-core-docs子命令用于对 collection 和 ansible-core 文档进行 lint 检查。前者在 创建 collection 文档站 中有更详细的描述。sphinx-init子命令用于设置基于 Sphinx 的 collection 文档站。这在 创建 collection 文档站 中有更详细的描述。ansible-output子命令可以直接将 ansible-playbook 的输出渲染到 RST 文件中。这在 更新 RST 文件中的 ansible-playbook 输出 中有更详细的描述。
使用 Sphinx 扩展¶
sphinx_antsibull_ext Sphinx 扩展 提供了最基本的 CSS 和若干个由所写 RST 文件使用的角色，以正确渲染文档。要使用它，请将其包含在您的 Sphinx 配置文件 conf.py 中
# Add it to 'extensions':
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext']
可以使用 antsibull_ext_color_scheme 配置来配置扩展所使用的配色方案。目前支持以下值：
default：默认颜色。default-dark：深色配色方案。default-autodark：根据prefers-color-scheme媒体查询选择默认颜色或深色。none：不定义颜色。如果您想通过自己的定义覆盖所有颜色，从而不需要包含默认颜色，可以使用此选项。
默认配色方案可以在 src/sphinx_antsibull_ext/css/colors-default.scss 中找到。有关颜色定义如何工作的详细信息，请参阅 MDN 关于使用 CSS 自定义属性的页面。
请注意，配色方案仅适用于 HTML 输出。LaTeX / PDF 输出的颜色是硬编码的，目前无法修改。
许可证¶
除非在代码中另有说明，否则本软件根据 GNU 通用公共许可证 v3 或更高版本的条款进行许可。请参阅 LICENSES/GPL-3.0-or-later.txt 获取许可证副本。
本仓库遵循 REUSE 规范 来声明版权和许可证信息。唯一的例外是 changelog/fragments/ 中的变更日志片段。