antsibull-docs -- Ansible 文档构建脚本发行说明¶

主题

v2.16.2
- 发行摘要
- Bugfix
v2.16.1
- 发行摘要
- Bugfix
v2.16.0
- 发行摘要
- 次要更改
v2.15.0
- 发行摘要
- 次要更改
v2.14.0
- 发行摘要
- 次要更改
v2.13.1
- 发行摘要
- Bugfix
v2.13.0
- 发行摘要
- 次要更改
- Bugfix
v2.12.0
- 发行摘要
- 次要更改
- Bugfix
v2.11.0
- 发行摘要
- 次要更改
- Bugfix
v2.10.0
- 发行摘要
- 次要更改
- Bugfix
v2.9.0
- 发行摘要
- 次要更改
v2.8.0
- 发行摘要
- 次要更改
- Bugfix
v2.7.0
- 发行摘要
- 次要更改
- Bugfix
v2.6.1
- 发行摘要
- Bugfix
v2.6.0
- 发行摘要
- 次要更改
- Bugfix
v2.5.0
- 发行摘要
- 次要更改
v2.4.0
- 发行摘要
- 次要更改
- 已弃用功能
- Bugfix
- 已知问题
v2.3.1
- 发行摘要
- Bugfix
v2.3.0
- 发行摘要
- 次要更改
- Bugfix
v2.2.0
- 发行摘要
- 次要更改
- Bugfix
v2.1.0
- 发行摘要
- 次要更改
- Bugfix
v2.0.0
- 发行摘要
- 主要更改
- 次要更改
- 重大更改/移植指南
- Bugfix
v1.11.0
- 发行摘要
- 次要更改
v1.10.0
- 发行摘要
- 主要更改
- 次要更改
- Bugfix
v1.9.0
- 发行摘要
- 次要更改
v1.8.2
- 发行摘要
- Bugfix
v1.8.1
- 发行摘要
- Bugfix
v1.8.0
- 发行摘要
- 次要更改
- Bugfix
v1.7.4
- 发行摘要
- Bugfix
v1.7.3
- 发行摘要
- Bugfix
v1.7.2
- 发行摘要
- Bugfix
v1.7.1
- 发行摘要
- Bugfix
v1.7.0
- 发行摘要
- 次要更改
- Bugfix
v1.6.1
- 发行摘要
- Bugfix
v1.6.0
- 发行摘要
- 次要更改
- Bugfix
v1.5.0
- 发行摘要
- 次要更改
- Bugfix
v1.4.0
- 发行摘要
- 次要更改
- Bugfix
v1.3.0
- 发行摘要
- 次要更改
- Bugfix
v1.2.2
- 发行摘要
- Bugfix
v1.2.1
- 发行摘要
- Bugfix
v1.2.0
- 发行摘要
- 次要更改
- Bugfix
v1.1.0
- 发行摘要
- 次要更改
v1.0.1
- 发行摘要
- Bugfix
v1.0.0
- 发行摘要
- 主要更改
- 次要更改
v0.1.0
- 发行摘要

v2.16.2¶

发行摘要¶

错误修复版本。

Bugfix¶

修复角色部分标题级别。示例和属性应低于角色入口点 (https://github.com/ansible-community/antsibull-docs/issues/366, https://github.com/ansible-community/antsibull-docs/pull/367)。

v2.16.1¶

发行摘要¶

错误修复版本。

Bugfix¶

还要考虑模块运行时元数据中的操作插件重定向/弃用，因为对于用户来说没有区别。此外，ansible.builtin.yum 只有一个操作插件重定向到 ansible.builtin.dnf，因此需要确保为 ansible.builtin.yum 生成存根页面 (https://github.com/ansible-community/antsibull-docs/pull/360)。

v2.16.0¶

发行摘要¶

功能发布。

次要更改¶

允许取消集合弃用 (https://github.com/ansible-community/antsibull-docs/pull/352)。
声明支持 Python 3.13 (https://github.com/ansible-community/antsibull-docs/pull/349)。
antsibull-docs 现在依赖于 antsibull-core >= 3.4.0 (https://github.com/ansible-community/antsibull-docs/pull/352)。

v2.15.0¶

发行摘要¶

Bugfix 和功能发布，它迁移到 Pydantic 2。

次要更改¶

将所有模型迁移到 Pydantic 2。这在很大程度上是透明的，除了验证错误消息略有更改，并且某些验证更加严格。例如，如果在描述中使用布尔值而不是字符串，现在会导致错误而不是静默强制转换。数字仍然接受用于字符串（例如，具有浮点值的 version_added，如 2.14）(https://github.com/ansible-community/antsibull-docs/pull/331, https://github.com/ansible-community/antsibull-core/pull/333, https://github.com/ansible-community/antsibull-core/pull/344)。
此项目现在依赖于 antsibull-core >= 3.2.0 和 pydantic 2 (https://github.com/ansible-community/antsibull-docs/pull/330)。
使用环境中的代理配置设置。查看 aiohttp 文档关于代理支持，了解支持哪些环境变量 (https://github.com/ansible/ansible-documentation/issues/1936, https://github.com/ansible-community/antsibull-docs/pull/346)。
对示例 INI 代码块使用语言 ini (https://github.com/ansible-community/antsibull-docs/pull/335)。
当使用 stable 和 devel 子命令渲染 Ansible 文档站点时，将显示有关已弃用集合的信息 (https://github.com/ansible-community/ansible-build-data/pull/450, https://github.com/ansible-community/antsibull-docs/pull/330)。
当使用 stable 和 devel 子命令渲染 Ansible 文档站点时，将添加已删除集合的存根页面 (https://github.com/ansible-community/ansible-build-data/pull/459, https://github.com/ansible-community/antsibull-docs/pull/341)。

v2.14.0¶

发行摘要¶

功能发布。

次要更改¶

添加对 antsibull-fileutils 的依赖项。antsibull-core 的某些功能正在移到那里，因此我们可以直接从那里使用它 (https://github.com/ansible-community/antsibull-docs/pull/322)。
在列表中的模块/插件/角色描述旁边添加弃用标记 (https://github.com/ansible-community/antsibull-docs/issues/141, https://github.com/ansible-community/antsibull-docs/pull/320)。
从 ansible.builtin 链接中删除 ansible-project Google Groups 邮件列表 (https://github.com/ansible-community/antsibull-docs/pull/325)。

v2.13.1¶

发行摘要¶

错误修复版本。

Bugfix¶

plugin 子命令使用的输出文件名在 rst 扩展名之前包含两个点 (https://github.com/ansible-community/antsibull-docs/issues/317, https://github.com/ansible-community/antsibull-docs/pull/318)。

v2.13.0¶

发行摘要¶

Bugfix 和功能发布。

次要更改¶

允许使用 --no-add-antsibull-docs-version 命令行标志或 antsibull-docs 配置文件中的 add_antsibull_docs_version = false 设置禁用将 antsibull-docs 版本添加到生成的文件中 (https://github.com/ansible-community/antsibull-docs/issues/304, https://github.com/ansible-community/antsibull-docs/pull/308)。
将依赖项 antsibull-docs-parser 的最低要求版本提升到 1.1.0。这允许使用新的空格删除功能 (https://github.com/ansible-community/antsibull-docs/pull/312)。
如果您正在使用 argcomplete，您现在可以制表符补全 antsibull-docs 命令行。有关如何在全局启用制表符补全的信息，请参阅 argcomplete README 中的激活全局补全。这还将制表符补全 Ansible 命令，例如 ansible-playbook 和 ansible-test (https://github.com/ansible-community/antsibull-docs/pull/302)。
大多数文档生成子命令现在都有一个 --cleanup 参数，该参数允许删除目标目录中不是由 antsibull-docs 创建的文件和目录 (https://github.com/ansible-community/antsibull-docs/pull/315)。
使用 sphinx-init 子命令创建构建脚本时不再使用 rsync (https://github.com/ansible-community/antsibull-docs/pull/315)。
从模板中删除多余的空格或转义空格 (https://github.com/ansible-community/antsibull-docs/pull/313)。
从渲染的模板中删除尾随空格和前导和尾随空行，并确保它们以换行符结尾（如果非空）(https://github.com/ansible-community/antsibull-docs/pull/314)。

Bugfix¶

修复每个命名空间列表中集合标题的 RST 转义。这会导致命名空间名称和单词 Namespace 之间在使用较新版本的 antsibull-docs-parser 时消失空格 (https://github.com/ansible-community/antsibull-docs/pull/311)。

v2.12.0¶

发行摘要¶

Bugfix 和功能发布。

次要更改¶

允许在集合链接的“通信”部分中提及论坛 (https://github.com/ansible-community/antsibull-docs/pull/288)。
将 antsibull-docs-parser 的最低依赖项提升到 1.0.2 或更高版本 (https://github.com/ansible-community/antsibull-docs/pull/290)。
lint-collection-docs 子命令现在会抱怨 docs/docsite/links.yml 中从社区集合模板获取的未更改默认值 (https://github.com/ansible-community/antsibull-docs/issues/273, https://github.com/ansible-community/antsibull-docs/pull/277)。
集合文档 linter 现在会报告空标记，例如 I()、L(,https://example.com) (https://github.com/ansible-community/antsibull-docs/pull/292)。

Bugfix¶

改进对 RST 空标记参数的处理 (https://github.com/ansible-community/antsibull-docs/pull/290)。
改进空或损坏的变更日志的渲染 (https://github.com/ansible-community/antsibull-docs/pull/289)。
移除段落前导空格，以避免意外的 RST 块引用（https://github.com/ansible-community/antsibull-docs/pull/289）。
将错误渲染为语言为 text 的代码块，而不是使用默认的词法分析器（https://github.com/ansible-community/antsibull-docs/pull/289）。

v2.11.0¶

版本摘要¶

功能和错误修复版本。

次要更改¶

支持角色入口点的示例（https://github.com/ansible-community/antsibull-docs/pull/244）。

错误修复¶

修复当 type=list 时对字典类型的 choices 的处理（https://github.com/ansible-community/antsibull-docs/pull/276）。
修复当存在 choices 时，对 type=list 的 default 的处理（https://github.com/ansible-community/antsibull-docs/pull/276）。

v2.10.0¶

版本摘要¶

Bugfix 和功能发布。

次要更改¶

现在可以通过在 docs/docsite/config.yml 中使用 changelog 选项，将集合的变更日志渲染为集合文档站点的一部分（https://github.com/ansible-community/antsibull-docs/issues/31，https://github.com/ansible-community/antsibull-docs/pull/267）。

错误修复¶

修复简化的 RST 输出中指向选项和返回值的内部链接（https://github.com/ansible-community/antsibull-docs/pull/269）。
在角色属性引用中包含角色（https://github.com/ansible-community/antsibull-docs/pull/269）。

v2.9.0¶

版本摘要¶

维护版本。

次要更改¶

添加对 antsibull-core v3 的支持（https://github.com/ansible-community/antsibull-docs/pull/261）。

v2.8.0¶

版本摘要¶

Bugfix 和功能发布。

次要更改¶

为选项表样式添加“暗黑模式”支持（https://github.com/ansible-community/antsibull-docs/pull/253，https://github.com/ansible-community/antsibull-docs/pull/258）。
添加对最新的 antsibull-core v3 预发布版本 3.0.0a1 的支持（https://github.com/ansible-community/antsibull-docs/pull/250）。
声明支持 Python 3.12（https://github.com/ansible-community/antsibull-docs/pull/255）。
现在可以覆盖 Antsibull Sphinx 扩展提供的 CSS 使用的颜色（https://github.com/ansible-community/antsibull-docs/pull/254）。

错误修复¶

修复最新 ansible-core devel 中（对于别名）的重复文档检测（https://github.com/ansible-community/antsibull-docs/pull/257）。

v2.7.0¶

版本摘要¶

错误修复和重构版本。

次要更改¶

显式设置 Galaxy 上下文，而不是依赖已弃用的功能（https://github.com/ansible-community/antsibull-docs/pull/234）。

错误修复¶

修复角色入口点中 seealso 的模式。插件引用现在可以工作（https://github.com/ansible-community/antsibull-docs/issues/237，https://github.com/ansible-community/antsibull-docs/pull/240）。
使 plugin seealso 条目中无效引用的错误报告更加精确（https://github.com/ansible-community/antsibull-docs/pull/240）。
支持新的 ansible-doc --json 输出字段 plugin_name（https://github.com/ansible-community/antsibull-docs/pull/242）。
使用库上下文中的某些字段，而不是应用程序上下文中已弃用且将从 antsibull-core 3.0.0 中删除的字段（https://github.com/ansible-community/antsibull-docs/pull/233）。

v2.6.1¶

版本摘要¶

错误修复版本。

错误修复¶

对于角色参数规范，允许 author、description 和 todo 为字符串而不是字符串列表，与 ansible-doc 以及模块和插件类似（https://github.com/ansible-community/antsibull-docs/pull/227）。
确保标题下划线对于宽 Unicode 字符具有正确的宽度（https://github.com/ansible-community/antsibull-docs/issues/228，https://github.com/ansible-community/antsibull-docs/pull/229）。

v2.6.0¶

版本摘要¶

修复 EXAMPLES 的解析并改进错误消息

次要更改¶

改进调用 ansible-doc 失败时的错误消息（https://github.com/ansible-community/antsibull-docs/pull/223）。

错误修复¶

当 EXAMPLES 具有 # fmt: <format> 指定的格式时，此值用于确定代码块类型（https://github.com/ansible-community/antsibull-docs/pull/225）。

v2.5.0¶

版本摘要¶

发布以支持更新的 Ansible Galaxy 代码库。

次要更改¶

默认集合 URL 模板已从 https://galaxy.ansible.com/{namespace}/{name} 更改为 https://galaxy.ansible.com/ui/repo/published/{namespace}/{name}/，以适应 2023 年 9 月 30 日 Galaxy 代码库的更改（https://github.com/ansible-community/antsibull-docs/issues/147，https://github.com/ansible-community/antsibull-docs/pull/220）。

v2.4.0¶

版本摘要¶

错误修复和功能发布。改进了对 html 以外的其他构建器的支持。

在 Ansible Galaxy 切换到新的 galaxy_ng 代码库后，将有一个后续版本，计划于 9 月 30 日发布。该版本只会调整 Galaxy 的 URL，除了潜在的错误修复。

次要更改¶

为其他基于 HTML 的 Sphinx 构建器（如 epub 和 singlehtml）添加基本支持（https://github.com/ansible-community/antsibull-docs/pull/201）。
调整默认 RST 输出，以更好地与 Spinx 的 LaTeX 构建器配合使用（https://github.com/ansible-community/antsibull-docs/pull/195）。
如果指定了 --use-current，则允许为 collections 子命令的集合名称指定通配符（https://github.com/ansible-community/antsibull-docs/pull/219）。
Antsibull-docs 现在依赖于 antsibull-core >= 2.1.0（https://github.com/ansible-community/antsibull-docs/pull/209）。
使用自定义指令创建集合链接。这使它们与其他构建器（而非 HTML 构建器）兼容（https://github.com/ansible-community/antsibull-docs/pull/200）。
修复 Spinx 的 LaTeX 构建器中嵌套选项和返回值的缩进（https://github.com/ansible-community/antsibull-docs/pull/198）。
改进语义标记中选项和返回值名称的 linting，以处理数组存根：如果字典不是选项的最后一部分，则禁止字典的数组存根（https://github.com/ansible-community/antsibull-docs/pull/208）。
改进 ansible.builtin 插件和模块的信息框，以解释 FQCN 并链接到 collection 关键字文档（https://github.com/ansible-community/antsibull-docs/pull/218）。
改进集合中模块、插件和角色的信息框，以显示它们不包含在 ansible-core 中，并显示有关如何检查是否安装了集合的说明（https://github.com/ansible-community/antsibull-docs/pull/218）。
将 antsibull-docs 版本作为注释或元数据插入到生成的文件中（https://github.com/ansible-community/antsibull-docs/pull/205）。
确保 antsibull Sphinx 扩展包含正确的版本（与 antsibull-docs 本身相同）和许可信息（GPL-3.0-or-later），并且该版本对于新版本保持最新（https://github.com/ansible-community/antsibull-docs/pull/202）。
将角色从模板和结构样式从样式表移动到 antsibull Sphinx 扩展。这确保 HTML 标签（如 <strong> 和 <em>）用于粗体和斜体文本，并且相同的格式用于 LaTeX 构建器（https://github.com/ansible-community/antsibull-docs/pull/199）。
支持 ansible-core 2.16 及更高版本的 ansible-doc 中的多个过滤器。当需要查询多个但少于所有已安装集合的文档时，这使得构建文档站点和 linting 更加高效（https://github.com/ansible-community/antsibull-docs/issues/193，https://github.com/ansible-community/antsibull-docs/pull/213）。
现在 current 子命令有一个 --skip-ansible-builtin 选项，该选项会跳过为 ansible.builtin 构建文档（https://github.com/ansible-community/antsibull-docs/pull/215）。
为 LaTeX 构建器的输出使用与 HTML 构建器输出相同的颜色（https://github.com/ansible-community/antsibull-docs/pull/199）。

已弃用功能¶

--use-html-blobs 功能已弃用，该功能用于为 ansible-docsite 输出格式插入选项和返回值表的 HTML blobs，该功能即将移除。HTML 表格会导致一些功能中断，例如对选项和返回值的引用。如果您认为此功能需要保留，请在 antsibull-docs 存储库中创建一个 issue 并提供充分的理由（https://github.com/ansible-community/antsibull-docs/pull/217）。

Bug 修复¶

记录并确保带有 --use-current 的 collection 子命令只能与集合名称一起使用（https://github.com/ansible-community/antsibull-docs/pull/214）。
修复 FQCN 检测（https://github.com/ansible-community/antsibull-docs/pull/214）。
collection 子命令声称支持目录路径，但实际上从未支持。从帮助中删除了对路径的提及，并添加了验证（https://github.com/ansible-community/antsibull-docs/pull/214）。
plugin 子命令声称支持插件文件路径，但实际上从未支持。从帮助中删除了对路径的提及（https://github.com/ansible-community/antsibull-docs/pull/214）。
当运行 antsibull-docs --help 时，--version 选项现在会显示正确的程序名称（https://github.com/ansible-community/antsibull-docs/pull/209）。
当运行 antsibull-docs --version 时，即使对于允许 importlib.metadata 显示正确版本的可编辑安装和其他安装，现在也会显示正确的版本（https://github.com/ansible-community/antsibull-docs/pull/209）。
当在角色中使用 action_group 或 platform 属性时，使用了未定义的 RST 符号（https://github.com/ansible-community/antsibull-docs/pull/206）。

已知问题¶

当使用除 HTML 和 LaTeX 之外的 Sphinx 构建器时，嵌套选项和返回值的缩进会丢失（https://github.com/ansible-community/antsibull-docs/pull/195）。

v2.3.1¶

版本摘要¶

修复了 Sphinx 扩展的 CSS 错误的 Bug 修复版本。

Bug 修复¶

修复 antsibull Sphinx 扩展 CSS，以便模块/插件/角色文档的选项/返回值锚点也可以在基于 WebKit 的浏览器（如 Gnome Web 和 Safari）上使用（https://github.com/ansible-community/antsibull-docs/issues/188, https://github.com/ansible-community/antsibull-docs/pull/189）。

v2.3.0¶

版本摘要¶

Bugfix 和功能发布。

次要更改¶

向 Sphinx 扩展添加一个 :ansplugin: 角色。这允许使用 fqcn#type 语法从语义标记中引用模块、插件或角色，而不是必须手动编写 ansible_collections.{fqcn}_{type} 标签。还可以使用类似于 :ref: 角色的 title <fqcn#type> 语法提供显式引用标题（https://github.com/ansible-community/antsibull-docs/pull/180）。
添加一个新的子命令 lint-core-docs，用于检查 ansible-core 文档（https://github.com/ansible-community/antsibull-docs/pull/182）。
添加一个新的子命令 collection-plugins，用于为集合中的所有插件和角色渲染文件，而无需任何索引（https://github.com/ansible-community/antsibull-docs/pull/177）。
添加对不同输出格式的支持。除了默认格式 ansible-docsite 之外，还支持新的**实验性**格式 simplified-rst。实验性意味着它在接下来的几个版本中可能会发生重大变化，直到它稳定下来。此类更改不会被视为破坏性更改，甚至可能只是错误修复（https://github.com/ansible-community/antsibull-docs/pull/177）。
使用 Dart sass 编译器而不是 sassc 来编译 Sphinx 扩展的 CSS（https://github.com/ansible-community/antsibull-docs/issues/185, https://github.com/ansible-community/antsibull-docs/pull/186）。
当 Sphinx 扩展中发生解析错误时，该扩展现在会在构建过程中发出错误消息，以及错误标记（https://github.com/ansible-community/antsibull-docs/pull/187）。

Bug 修复¶

在检查对其他模块和插件的引用时，考虑模块/插件别名（https://github.com/ansible-community/antsibull-docs/pull/184）。
确保实际列出了插件的所有别名（https://github.com/ansible-community/antsibull-docs/pull/183）。
在查找重定向时，没有正确考虑 ansible-core 中的 aliases 字段和文件系统重定向。这确保创建所有重定向存根，并且不会出现重复项，这与 ansible-core 是否以可编辑模式安装无关（https://github.com/ansible-community/antsibull-docs/pull/183）。

v2.2.0¶

版本摘要¶

改进渲染和检查的 Bug 修复和功能发布。

次要更改¶

集合文档检查器 - 还验证 seealso 模块和插件目标（https://github.com/ansible-community/antsibull-docs/issues/168, https://github.com/ansible-community/antsibull-docs/pull/171）。
在检查集合插件文档时，请确保在引用列表中的子选项或子返回值时使用数组存根 [...]，并且不要在列表和字典之外使用（https://github.com/ansible-community/antsibull-docs/pull/173）。

Bug 修复¶

修复 Sphinx 扩展为选项和返回值创建节点的方式，使其在内部引用、外部 (intersphinx) 引用和未解析的引用方面看起来相同（https://github.com/ansible-community/antsibull-docs/pull/175）。
确保 :ansopt: 和 :ansretval: 创建与 RST 文件中创建的标签相同的引用（https://github.com/ansible-community/antsibull-docs/issues/167, https://github.com/ansible-community/antsibull-docs/pull/172）。
确保损坏的 :ansopt: 和 :ansretval: 参数会导致正确呈现的错误消息（https://github.com/ansible-community/antsibull-docs/pull/175）。
在尝试将不存在的插件的描述复制到 seealso 时，在某些情况下添加了对这些不存在的插件的引用，从而导致文档增强过程崩溃（https://github.com/ansible-community/antsibull-docs/pull/169）。

v2.1.0¶

版本摘要¶

具有许多与语义标记和验证相关的改进的功能和 Bug 修复版本。

次要更改¶

添加 --disallow-unknown-collection-refs 选项，以禁止引用 --validate-collection-refs 所涵盖集合之外的其他集合（https://github.com/ansible-community/antsibull-docs/pull/157）。
向 lint-collection-docs 子命令添加 --validate-collection-refs 选项，以控制应验证（其他）集合及其选项和返回值中对插件/模块/角色名称的哪些引用（https://github.com/ansible-community/antsibull-docs/pull/157）。
添加新的集合配置字段 envvar_directives，该字段允许声明哪些环境变量在集合的额外文档站点文档中使用 .. envvar:: 指令声明。除了插件配置信息和 ansible-core 配置信息之外，这用于确定环境变量是否可引用（https://github.com/ansible-community/antsibull-docs/pull/166）。
向 antsibull-docs Sphinx 扩展添加角色 :ansenvvar: 和 :ansenvvarref:（https://github.com/ansible-community/antsibull-docs/pull/166）。
根据环境变量是否已知可引用，使用 :ansenvvarref: 或 :ansenvvar: 呈现 E(...) 标记（https://github.com/ansible-community/antsibull-docs/pull/166）。
在检查集合文档中的标记时，验证插件/模块/角色名称，以及同一集合、（传递地）依赖的集合和 ansible.builtin 中其他插件/模块/角色的选项/返回值名称（https://github.com/ansible-community/antsibull-docs/pull/157）。
在检查集合文档中的语义标记时，在检查 O() 值时也接受别名（https://github.com/ansible-community/antsibull-docs/pull/155）。
在引用多段文本（如 description）中的标记时，现在会在错误消息中包含段落编号（https://github.com/ansible-community/antsibull-docs/pull/163）。

Bug 修复¶

允许角色入口点弃用，而无需指定角色从中删除的集合（https://github.com/ansible-community/antsibull-docs/pull/156）。
如果“Why”或“Alternative”文本需要多行，则正确缩进模块/插件和角色入口点弃用（https://github.com/ansible-community/antsibull-docs/pull/156）。
在为 lint-collection-docs 子命令收集集合依赖项时，一个 bug 阻止了重复检测工作（https://github.com/ansible-community/antsibull-docs/pull/160）。

v2.0.0¶

发布摘要¶

此为主要新版本，放弃了对旧版 Python 和 Ansible/ansible-base/ansible-core 版本的支持。

主要变更¶

将 pyproject 构建后端从 poetry-core 更改为 hatchling。pip install antsibull-docs 的工作方式与之前完全相同，但某些用户可能会受到影响，具体取决于他们构建/安装项目的方式（https://github.com/ansible-community/antsibull-docs/pull/115）。

次要变更¶

允许 devel 和 stable 子命令使用当前安装的 ansible-core 版本（https://github.com/ansible-community/antsibull-docs/pull/121）。
Ansibull-docs 现在不再直接依赖于 sh（https://github.com/ansible-community/antsibull-docs/pull/122）。
将 sphinx-init 子命令写入的 antsibull-docs 需求的版本范围提升为 >= 2.0.0, < 3.0.0。之前，此范围设置为 >=2.0.0a2, <3.0.0（https://github.com/ansible-community/antsibull-docs/pull/151）。
现在依赖于 antsibull-core 2.0.0 或更高版本；不再支持 antsibull-core 1.x.y（https://github.com/ansible-community/antsibull-docs/pull/122）。
删除 Python 3.6 和 3.7 的残留兼容性代码（https://github.com/ansible-community/antsibull-docs/pulls/70）。
支持每个集合的文档配置文件 docs/docsite/config.yml。它也会被 lint-collection-docs 子命令检查（https://github.com/ansible-community/antsibull-docs/pull/134）。
sphinx-init 子命令创建的 requirements.txt 文件中的 antsibull-docs 需求现在具有版本范围 >= 2.0.0, < 3.0.0（https://github.com/ansible-community/antsibull-docs/pull/126）。
已添加依赖项 antsibull-docs-parser，并用于处理 Ansible 标记（https://github.com/ansible-community/antsibull-docs/pull/124）。

重大变更/移植指南¶

禁用除 community.general < 6.0.0 和 community.network < 5.0.0 之外的所有集合的平面映射。您可以通过在 docs/docsite/config.yml 中设置 flatmap: true 来为您的集合启用平面映射（https://github.com/ansible-community/antsibull-docs/pull/134）。
放弃对 Python 3.6、3.7 和 3.8 的支持（https://github.com/ansible-community/antsibull-docs/pull/115）。
在自建 venv 之外调用 ansible、ansible-galaxy 或 ansible-doc 时，不再从环境中删除 PYTHONPATH（https://github.com/ansible-community/antsibull-docs/pull/121）。
不再支持 Ansible 2.9、ansible-base 2.10 以及 ansible-core 2.11 和 2.12。最低要求的 ansible-core 版本为 2.13。这允许更简单、更高效的文档解析和信息检索（https://github.com/ansible-community/antsibull-docs/pull/120）。
已删除配置文件中 doc_parsing_backend 的 ansible-doc 和 ansible-internal 值。将该值更改为 auto 以获得最佳兼容性（https://github.com/ansible-community/antsibull-docs/pull/120）。

错误修复¶

将 sphinx-init 子命令写入的 antsibull-docs 需求的版本范围提升为 >= 2.0.0a2, < 3.0.0。之前，此范围设置为 >=2.0.0, <3.0.0，无法满足（https://github.com/ansible-community/antsibull-docs/pull/149）。
使用应用程序上下文中的 doc_parsing_backend 而不是库上下文中的。这可以防止从 antsibull-core 库上下文中删除 doc_parsing_backend（https://github.com/ansible-community/antsibull-docs/pull/125）。

v1.11.0¶

发布摘要¶

功能发布。

次要变更¶

添加对角色中语义标记的支持（https://github.com/ansible-community/antsibull-docs/pull/113）。
标记代码的内部重构（https://github.com/ansible-community/antsibull-docs/pull/108）。
当使用 --plugin-docs 时，可以通过传递 --skip-rstcheck 来告知 lint-collection-docs 子命令不运行 rstcheck。这加快了大型集合的测试速度（https://github.com/ansible-community/antsibull-docs/pull/112）。
当传递 --plugin-docs 时，lint-collection-docs 子命令现在还会验证 Ansible 标记。它还可以使用新的 --disallow-semantic-markup 选项确保不使用语义标记。例如，集合可以使用此选项来避免将语义标记向后移植到较旧的稳定分支（https://github.com/ansible-community/antsibull-docs/pull/112）。

v1.10.0¶

发布摘要¶

Bugfix 和功能发布。

主要变更¶

支持文档中的新语义标记（https://github.com/ansible-community/antsibull-docs/pull/4）。

次要变更¶

向插件页面添加关于位置参数和命名参数排序的说明。还提到了查找的位置参数和关键字参数（https://github.com/ansible-community/antsibull-docs/pull/101）。
更新角色参数规范的架构，以允许在入口点级别指定属性。这些属性现在也会在存在时呈现（https://github.com/ansible-community/antsibull-docs/pull/103）。

错误修复¶

显式声明 sh 依赖项并将其限制为 2.0.0 之前。还显式声明了对 pydantic、semantic_version、aiohttp、twiggy 和 PyYAML 的依赖（https://github.com/ansible-community/antsibull-docs/pull/99）。
将 pydantic 依赖项限制为主要版本 1（https://github.com/ansible-community/antsibull-docs/pull/102）。

v1.9.0¶

发布摘要¶

功能发布。

次要变更¶

改进由 antsibull-docs sphinx-init 生成的构建脚本，以更改到脚本所在的目录，而不是硬编码脚本的路径。这还修复了现有路径未被引用的错误（https://github.com/ansible-community/antsibull-docs/issues/91，https://github.com/ansible-community/antsibull-docs/pull/92）。
在回调插件页面上显示回调插件类型。还按回调插件类型编写回调索引（https://github.com/ansible-community/antsibull-docs/issues/89，https://github.com/ansible-community/antsibull-docs/pull/90）。

v1.8.2¶

发布摘要¶

错误修复版本。

错误修复¶

修复了 sphinx-init 子命令的新选项 --extra-html-context 和 --extra-html-theme-options（https://github.com/ansible-community/antsibull-docs/pull/86）。

v1.8.1¶

发布摘要¶

错误修复版本。

错误修复¶

在为面包屑创建 toctrees 时，将插件类型的子树放在插件类型的节中（https://github.com/ansible-community/antsibull-docs/pull/83）。

v1.8.0¶

发布摘要¶

功能和错误修复版本。

次要变更¶

向 sphinx-init 子命令添加新选项 --project、--copyright、--title、--html-short-title、--extra-conf、--extra-html-context 和 --extra-html-theme-options，以允许自定义生成的 conf.py Sphinx 配置（https://github.com/ansible-community/antsibull-docs/pull/77）。
如果未提供描述，则自动使用模块或插件的简短描述作为“另请参阅”描述（https://github.com/ansible-community/antsibull-docs/issues/64，https://github.com/ansible-community/antsibull-docs/pull/74）。
现在可以提供现有文件的路径，以用作 antsibull-docs sphinx-init 的 rst/index.rst（https://github.com/ansible-community/antsibull-docs/pull/68）。
与 antsibull-core 2.x.y 兼容（https://github.com/ansible-community/antsibull-docs/pull/78）。
删除对 forced_action_plugin 的支持，这是一个在属性开发阶段被删除的模块属性（https://github.com/ansible-community/antsibull-docs/pull/63）。
如果 Ansible 版本早于 2.7，则停止提及为 Ansible 添加功能的版本（https://github.com/ansible-community/antsibull-docs/pull/76）。
antsibull-docs sphinx-init 创建的默认 index.rst 包括新的环境变量索引（https://github.com/ansible-community/antsibull-docs/pull/80）。
为环境变量使用正确的标记（envvar 角色）。编译插件使用的所有环境变量的索引（https://github.com/ansible-community/antsibull-docs/pull/73）。

错误修复¶

确保 sphinx-init 子命令创建的 build.sh 为其创建的 temp-rst 目录上的 antsibull-docs 设置适当的权限（https://github.com/ansible-community/antsibull-docs/pull/79）。

v1.7.4¶

发布摘要¶

错误修复版本。

错误修复¶

删除了由 antsibull-docs sphinx-init 创建的 requirements.txt 文件中的 sphinx 限制，因为 sphinx-rtd-theme 中的错误已修复（https://github.com/ansible-community/antsibull-docs/pull/69）。
由 antsibull-docs sphinx-init 创建的 rst/index.rst 文件模板的许可证头注释不正确，因此显示在模板文件中 (https://github.com/ansible-community/antsibull-docs/pull/67)。
当使用 --squash-hierarchy 时，不要在集合的索引页面上提及集合列表 (https://github.com/ansible-community/antsibull-docs/pull/72)。

v1.7.3¶

版本摘要¶

错误修复版本。

Bug 修复¶

修复 action_group 属性的渲染 (https://github.com/ansible-community/antsibull-docs/pull/62)。

v1.7.2¶

版本摘要¶

错误修复版本。

Bug 修复¶

修复 version_added 对 ansible.builtin 0.x 的处理，将其表示为 Ansible 0.x 而不是 ansible-core 0.x (https://github.com/ansible-community/antsibull-docs/pull/61)。

v1.7.1¶

版本摘要¶

错误修复版本。

Bug 修复¶

当 deps 文件中存在 _python 条目时，防止在 stable 文档站点构建期间崩溃 (https://github.com/ansible-community/antsibull-docs/pull/57)。

v1.7.0¶

版本摘要¶

Bugfix 和功能发布。

次要更改¶

向 sphinx-init 子命令添加 --intersphinx 选项，以允许向 conf.py 添加额外的 intersphinx_mapping 条目 (https://github.com/ansible-community/antsibull-docs/issues/35, https://github.com/ansible-community/antsibull-docs/pull/44)。
允许集合的 docs/docsite/extra-docs.yml 中的 toctree 条目为一个带有 ref 和 title 键的字典，而不是仅作为字符串的引用 (https://github.com/ansible-community/antsibull-docs/pull/45)。
Antsibull-docs 现在依赖于 packaging (https://github.com/ansible-community/antsibull-docs/pull/49)。
如果集合的 meta/runtime.yml 指定了 requires_ansible，则集合的索引页面现在包含该集合支持的 ansible-core 版本 (https://github.com/ansible-community/antsibull-docs/issues/48, https://github.com/ansible-community/antsibull-docs/pull/49)。
改进了 lint-collection-docs 命令的输出；特别是，多行消息现在会缩进 (https://github.com/ansible-community/antsibull-docs/pull/52)。
当 ansible-core 没有安装在用于 antsibull-docs 的同一个 Python 解释器/venv 中时，使用 ansible --version 来确定 ansible-core 版本 (https://github.com/ansible-community/antsibull-docs/pull/50)。
对所有值使用代码格式，例如选择条目、默认值和示例 (https://github.com/ansible-community/antsibull-docs/issues/38, https://github.com/ansible-community/antsibull-docs/pull/42)。

Bug 修复¶

避免过长的别名列表导致左列过宽 (https://github.com/ansible-collections/amazon.aws/issues/1101, https://github.com/ansible-community/antsibull-docs/pull/54)。
使 lint-collection-docs --plugin-docs 子命令真正工作 (https://github.com/ansible-community/antsibull-docs/pull/47)。

v1.6.1¶

版本摘要¶

ansible-core 2.14 的 Bug 修复版本。

Bug 修复¶

修复顶级 version_added 的制定 (https://github.com/ansible-community/antsibull-docs/pull/43)。

v1.6.0¶

版本摘要¶

Bugfix 和功能发布。

次要更改¶

允许将选择指定为字典而不是列表 (https://github.com/ansible-community/antsibull-docs/pull/36)。
使用 JSON 序列化器格式化选择 (https://github.com/ansible-community/antsibull-docs/pull/37)。
在示例中使用特殊的序列化器格式化 INI 值 (https://github.com/ansible-community/antsibull-docs/pull/37)。

Bug 修复¶

避免在 HTML 输出中错误地转义包含 _ 的集合名称 (https://github.com/ansible-community/antsibull-docs/pull/41)。
对于没有默认值的 INI 示例，按预期写入 VALUE 而不是 None (https://github.com/ansible-community/antsibull-docs/pull/37)。
正确格式化 INI 示例的列表 (https://github.com/ansible-community/antsibull-docs/pull/37)。
sphinx-init 子命令的 requirement.txt 文件避免使用 Sphinx 5.2.0.post0，这会触发 sphinx-rtd-theme 中的一个错误，该错误恰好是 sphinx-init 使用的默认主题 sphinx_ansible_theme 的父主题 (https://github.com/ansible-community/antsibull-docs/issues/39, https://github.com/ansible-community/antsibull-docs/pull/40)。

v1.5.0¶

版本摘要¶

功能和错误修复版本。

次要更改¶

检测过滤器和测试插件别名，避免多次发出它们。而是插入重定向，以便创建存根页面 (https://github.com/ansible-community/antsibull-docs/pull/33)。
在版本添加的集合名称中，将 ansible.builtin 替换为 ansible-core、ansible-base 或 Ansible。另外，写入 <collection_name> <version> 而不是 <version> of <collection_name> (https://github.com/ansible-community/antsibull-docs/pull/34)。

Bug 修复¶

修复版本添加语句中集合名称的转义，并修复角色选项的集合名称 (https://github.com/ansible-community/antsibull-docs/pull/34)。

v1.4.0¶

版本摘要¶

功能和错误修复版本。

次要更改¶

sphinx-init 子命令现在还会创建一个 antsibull-docs.cfg 文件，并将配置设置从 build.sh 中的 CLI 标志移动到此配置文件 (https://github.com/ansible-community/antsibull-docs/pull/26)。
有两个新的选项用于显式指定的配置文件，名为 collection_url 和 collection_install。这些选项允许覆盖指向集合的 URL（默认链接到 galaxy.ansible.com）和安装集合的命令（默认使用 ansible-galaxy collection install）。当记录（内部）在 Ansible Galaxy 上不可用的集合时，这很有用。由 sphinx-init 子命令生成的默认 antsibull-docs.cfg 显示了如何配置此项 (https://github.com/ansible-community/antsibull-docs/issues/15, https://github.com/ansible-community/antsibull-docs/pull/26)。
当生成插件错误页面或在插件或角色中显示非致命错误时，如果可用，则链接到集合的问题跟踪器而不是集合的 URL (https://github.com/ansible-community/antsibull-docs/pull/29)。

Bug 修复¶

当某些值为 None 而键存在时，使对错误文档的处理更加健壮 (https://github.com/ansible-community/antsibull-docs/pull/32)。

v1.3.0¶

版本摘要¶

功能和错误修复版本。

次要更改¶

确保 default、choices 和 sample 的值使用为选项/返回值指定的类型 (https://github.com/ansible-community/antsibull-docs/pull/19)。
如果插件或模块列出了要求，则在顶部的安装行旁边添加一个免责声明，说明还需要其他要求 (https://github.com/ansible-community/antsibull-docs/issues/23, https://github.com/ansible-community/antsibull-docs/pull/24)。
仅对于官方文档站点构建（子命令 devel 和 stable），显示“如果您正在使用 ansible 包，则可能已经安装了此集合”的免责声明。此外，在官方文档站点构建中包含角色的此免责声明 (https://github.com/ansible-community/antsibull-docs/pull/25)。
对布尔值使用 true 和 false 而不是 yes 和 no (https://github.com/ansible-community/community-topics/issues/116, https://github.com/ansible-community/antsibull-docs/pull/19)。
在处理格式化指令时，请确保正确转义所有其他文本以用于 RST 或 HTML，而不是逐字包含它 (https://github.com/ansible-community/antsibull-docs/issues/21, https://github.com/ansible-community/antsibull-docs/pull/22)。

Bug 修复¶

改进 HTML 表格块的缩进，以避免生成无效 RST 的极端情况 (https://github.com/ansible-community/antsibull-docs/pull/22)。

v1.2.2¶

版本摘要¶

错误修复版本。

Bug 修复¶

修复 rstcheck-core 支持 (https://github.com/ansible-community/antsibull-docs/pull/20)。

v1.2.1¶

版本摘要¶

错误修复版本。

Bug 修复¶

不要像 Jinja2 tojson 过滤器那样在 JSON 格式的默认值和示例中转义 <、>、& 和 '。另外，通过确保 , 后跟一个空格来改进格式 (https://github.com/ansible-community/antsibull-docs/pull/18)。
在解析文档构建的 ansible-galaxy collection list 输出时，忽略了集合过滤器 (https://github.com/ansible-community/antsibull-docs/issues/16, https://github.com/ansible-community/antsibull-docs/pull/17)。

v1.2.0¶

版本摘要¶

功能和错误修复版本。

次要更改¶

支持来自语义标记规范的插件 seealso (https://github.com/ansible-community/antsibull-docs/pull/8)。
lint-collection-docs 子命令有一个新的布尔标志 --plugin-docs，它将插件文档渲染为 RST 并使用 rstcheck 验证它们。这可以用作 CI 中渲染文档站点的轻量级版本 (https://github.com/ansible-community/antsibull-docs/pull/12)。
源存储库中的文件现在遵循 REUSE 规范。唯一的例外是 changelogs/fragments/ 中的更改日志片段 (https://github.com/ansible-community/antsibull-docs/pull/14)。

Bug 修复¶

确保当插件在 positional 中提及测试或过滤器参数时，_input 不会显示两次 (https://github.com/ansible-community/antsibull-docs/pull/10)。
将 rstcheck 4.x 和 5.x 标记为兼容。也支持 rstcheck 6.x (https://github.com/ansible-community/antsibull-docs/pull/13)。

v1.1.0¶

发布摘要¶

功能发布，支持 ansible-core 2.14 的 sidecar 文档功能。

次要变更¶

如果 lookup 插件具有以 _ 开头的单个返回值，则该返回值现在标记为 Return value（https://github.com/ansible-community/antsibull-docs/pull/6）。
如果 lookup 插件具有名为 _terms 的选项，则现在它会显示在自己的 Terms 部分中，而不是在常规的 Parameters 部分中（https://github.com/ansible-community/antsibull-docs/pull/6）。
更强大的解析错误处理，当 ansible-doc 无法提取文档时（https://github.com/ansible-community/antsibull-docs/pull/6）。
支持参数类型 any，并将 raw 显示为 any（https://github.com/ansible-community/antsibull-docs/pull/6）。
当使用 ansible-core 2.14+ 时，支持 test 和 filter 插件。这适用于当前 ansible-core 的 devel 分支（https://github.com/ansible-community/antsibull-docs/pull/6）。

v1.0.1¶

发布摘要¶

错误修复版本。

错误修复¶

确保在 docutil 的规范化下，模块/插件选项和返回值的别名导致相同的 RST 标签时，只发出一次（https://github.com/ansible-community/antsibull-docs/pull/7）。
正确转义生成的 HTML 中的模块/插件选项和返回值 slug（https://github.com/ansible-community/antsibull-docs/pull/7）。

v1.0.0¶

发布摘要¶

第一个稳定版本。

主要变更¶

从 1.0.0 版本开始，antsibull-docs 将遵循语义版本控制，并旨在在主要发布周期内不对命令行 API (antsibull-docs) 提供向后不兼容的更改。我们明确排除代码兼容性。 antsibull-docs 不应该作为库使用，并且当作为库使用时，它可能不符合语义版本控制（https://github.com/ansible-community/antsibull-docs/pull/2）。

次要变更¶

仅在 stable 和 devel 子命令中提及“这些是 docs.ansible.com 上托管文档的集合”（https://github.com/ansible-community/antsibull-docs/pull/3）。
停止使用 antsibull-core 中正在删除的某些 API（https://github.com/ansible-community/antsibull-docs/pull/1）。

v0.1.0¶

发布摘要¶

初始版本。antsibull-docs 工具与 antsibull 0.43.0 中的工具兼容。