2.3.1

Release Summary

Bugfix release with a CSS fix for the Sphinx extension.

Bugfixes

• Fix antsibull Sphinx extension CSS so that the option/return value anchors for module/plugin/role documentation can also be used on WebKit-based browsers such as Gnome Web and Safari (#188, #189).

2.3.0

Release Summary

Bugfix and feature release.

Minor Changes

• Add a :ansplugin: role to the Sphinx extension. This allows to reference a module, plugin, or role with the fqcn#type syntax from semantic markup instead of having to manually compose a ansible_collections.{fqcn}_{type} label. An explicit reference title can also be provided with the title <fqcn#type> syntax similar to the :ref: role (#180).
• Add a new subcommand lint-core-docs which lints the ansible-core documentation (#182).
• Add a new subcommand, collection-plugins, for rendering files for all plugins and roles in a collection without any indexes (#177).
• Add support for different output formats. Next to the default format, ansible-docsite, a new experimental format simplified-rst is supported. Experimental means that it will likely change considerably in the next few releases until it stabilizes. Such changes will not be considered breaking changes, and could potentially even be bugfixes (#177).
• Use Dart sass compiler instead of sassc to compile CSS for Sphinx extension (#185, #186).
• When parsing errors happen in the Sphinx extension, the extension now emits error messages during the build process in addition to error markup (#187).

Bugfixes

• Consider module/plugin aliases when linting references to other modules and plugins (#184).
• Make sure that all aliases are actually listed for plugins (#183).
• When looking for redirects, the aliases field and filesystem redirects in ansible-core were not properly considered. This ensures that all redirect stubs are created, and that no duplicates show up, not depending on whether ansible-core is installed in editable mode or not (#183).

2.2.0

Release Summary

Bugfix and feature release improving rendering and linting.

Minor Changes

• Collection docs linter - also validate seealso module and plugin destinations (#168, #171).
• When linting collection plugin docs, make sure that array stubs [...] are used when referencing sub-options or sub-return values inside lists, and are not used outside lists and dictionaries (#173).

Bugfixes

• Fix the way the Sphinx extension creates nodes for options and return values so they look identical for internal references, external (intersphinx) references, and unresolved references (#175).
• Make sure that :ansopt: and :ansretval: create the same references as the labels created in the RST files (#167, #172).
• Make sure that broken :ansopt: and :ansretval: parameters result in correctly rendered error messages (#175).
• When trying to copying descriptions of non-existing plugins to seealso, references to these non-existing plugins were added in some cases, crashing the docs augmentation process (#169).

1.11.1

Release Summary

Bugfix release.

Bugfixes

• Allow role entrypoint deprecations without having to specify the collection the role is removed from (#156).
• Fix the way the Sphinx extension creates nodes for options and return values so they look identical for internal references, external (intersphinx) references, and unresolved references (#175).
• Indent module/plugin and role entrypoint deprecations correctly if 'Why' or 'Alternative' texts need more than one line (#156).
• Make sure that :ansopt: and :ansretval: create the same references as the labels created in the RST files (#167, #172).
• Make sure that broken :ansopt: and :ansretval: parameters result in correctly rendered error messages (#175).
• Use doc_parsing_backend from the application context instead of the library context. This prevents removal of doc_parsing_backend from the antsibull-core library context (#125).
• When collecting collection dependencies for the lint-collection-docs subcommand, a bug prevented the duplicate detection to work (#160).
• When trying to copying descriptions of non-existing plugins to seealso, references to these non-existing plugins were added in some cases, crashing the docs augmentation process (#169).

2.1.0

Release Summary

Feature and bugfix release with many improvements related to semantic markup and validation.

Minor Changes

• Add option --disallow-unknown-collection-refs to disallow references to other collections than the one covered by --validate-collection-refs (#157).
• Add option --validate-collection-refs to the lint-collection-docs subcommand to also control which references to plugin/module/role names in (other) collections and their options and return values should be validated (#157).
• Add the new collection config field envvar_directives which allows to declare which environment variables are declared with an .. envvar:: directive in the collection's extra docsite documentation. This is used, next to the plugin configuration information and the ansible-core configuration information, to determine whether an environment variable is referencable or not (#166).
• Add the roles :ansenvvar: and :ansenvvarref: to the antsibull-docs Sphinx extension (#166).
• Render E(...) markup with :ansenvvarref: or :ansenvvar: depending on whether the environment variable is known to be referencable or not (#166).
• When linting markup in collection docs, validate plugin/module/role names, and also option/return value names for other plugins/modules/roles in the same collection, (transitively) dependent collections, and ansible.builtin (#157).
• When linting semantic markup in collection docs, also accept aliases when checking O() values (#155).
• When refering to markup in multi-paragraph texts, like description, now includes the paragraph number in error messages (#163).

Bugfixes

• Allow role entrypoint deprecations without having to specify the collection the role is removed from (#156).
• Indent module/plugin and role entrypoint deprecations correctly if 'Why' or 'Alternative' texts need more than one line (#156).
• When collecting collection dependencies for the lint-collection-docs subcommand, a bug prevented the duplicate detection to work (#160).

2.0.0

Release Summary

Major new release that drops support for older Python and Ansible/ansible-base/ansible-core versions.

Major Changes

• Change pyproject build backend from poetry-core to hatchling. pip install antsibull-docs works exactly the same as before, but some users may be affected depending on how they build/install the project (#115).

Minor Changes

• Allow to use the currently installed ansible-core version for the devel and stable subcommands (#121).
• Ansibull-docs now no longer depends directly on sh (#122).
• Bump version range of antsibull-docs requirement written by sphinx-init subcommand to >= 2.0.0, < 3.0.0. Previously, this was set to >=2.0.0a2, <3.0.0 (#151).
• Now depends antsibull-core 2.0.0 or newer; antsibull-core 1.x.y is no longer supported (#122).
• Remove residual compatability code for Python 3.6 and 3.7 (https://github.com/ansible-community/antsibull-docs/pulls/70).
• Support a per-collection docs config file docs/docsite/config.yml. It is also linted by the lint-collection-docs subcommand (#134).
• The antsibull-docs requirement in the requirements.txt file created by the sphinx-init subcommand now has version range >= 2.0.0, < 3.0.0 (#126).
• The dependency antsibull-docs-parser <https://github.com/ansible-community/antsibull-docs-parser>__ has been added and is used for processing Ansible markup (#124).

Breaking Changes / Porting Guide

• Disable flatmapping for all collections except community.general < 6.0.0 and community.network < 5.0.0. You can enable flatmapping for your collection by setting flatmap: true in docs/docsite/config.yml (#134).
• Drop support for Python 3.6, 3.7, and 3.8 (#115)."
• No longer removes PYTHONPATH from the environment when calling ansible, ansible-galaxy, or ansible-doc outside a self-created venv (#121).
• No longer supports Ansible 2.9, ansible-base 2.10, and ansible-core 2.11 and 2.12. The minimum required ansible-core version is 2.13. This allows for simpler and more efficient docs parsing and information retrieval (#120).
• The ansible-doc and ansible-internal values for doc_parsing_backend in the configuration file have been removed. Change the value to auto for best compatibility (#120).

Bugfixes

• Bump version range of antsibull-docs requirement written by sphinx-init subcommand to >= 2.0.0a2, < 3.0.0. Previously, this was set to >=2.0.0, <3.0.0 which could not be satisfied (#149).
• Use doc_parsing_backend from the application context instead of the library context. This prevents removal of doc_parsing_backend from the antsibull-core library context (#125).

2.0.0a2

Release Summary

Hotfix to make sphinx-init work properly.

Bugfixes

• Bump version range of antsibull-docs requirement written by sphinx-init subcommand to >= 2.0.0a2, < 3.0.0. Previously, this was set to >=2.0.0, <3.0.0 which could not be satisfied (#149).

2.0.0a1

Release Summary

Pre-release of new major 2.0.0 release.

Major Changes

• Change pyproject build backend from poetry-core to hatchling. pip install antsibull-docs works exactly the same as before, but some users may be affected depending on how they build/install the project (#115).

Minor Changes

• Allow to use the currently installed ansible-core version for the devel and stable subcommands (#121).
• Ansibull-docs now no longer depends directly on sh (#122).
• Now depends antsibull-core 2.0.0 or newer; antsibull-core 1.x.y is no longer supported (#122).
• Remove residual compatability code for Python 3.6 and 3.7 (https://github.com/ansible-community/antsibull-docs/pulls/70).
• Support a per-collection docs config file docs/docsite/config.yml. It is also linted by the lint-collection-docs subcommand (#134).
• The antsibull-docs requirement in the requirements.txt file created by the sphinx-init subcommand now has version range >= 2.0.0, < 3.0.0 (#126).
• The dependency antsibull-docs-parser <https://github.com/ansible-community/antsibull-docs-parser>__ has been added and is used for processing Ansible markup (#124).

Breaking Changes / Porting Guide

• Disable flatmapping for all collections except community.general < 6.0.0 and community.network < 5.0.0. You can enable flatmapping for your collection by setting flatmap: true in docs/docsite/config.yml (#134).
• Drop support for Python 3.6, 3.7, and 3.8 (#115)."
• No longer removes PYTHONPATH from the environment when calling ansible, ansible-galaxy, or ansible-doc outside a self-created venv (#121).
• No longer supports Ansible 2.9, ansible-base 2.10, and ansible-core 2.11 and 2.12. The minimum required ansible-core version is 2.13. This allows for simpler and more efficient docs parsing and information retrieval (#120).
• The ansible-doc and ansible-internal values for doc_parsing_backend in the configuration file have been removed. Change the value to auto for best compatibility (#120).

Bugfixes

• Use doc_parsing_backend from the application context instead of the library context. This prevents removal of doc_parsing_backend from the antsibull-core library context (#125).

1.11.0

Release Summary

Feature release.

Minor Changes

• Add support for semantic markup in roles (#113).
• Internal refactoring of markup code (#108).
• The lint-collection-docs subcommand can be told not to run rstcheck when --plugin-docs is used by passing --skip-rstcheck. This speeds up testing for large collections (#112).
• The lint-collection-docs subcommand will now also validate Ansible markup when --plugin-docs is passed. It can also ensure that no semantic markup is used with the new --disallow-semantic-markup option. This can for example be used by collections to avoid semantic markup being backported to older stable branches (#112).

1.10.0

Release Summary

Bugfix and feature release.

Major Changes

• Support new semantic markup in documentation (#4).

Minor Changes

• Add a note about the ordering of positional and named parameter to the plugin page. Also mention positional and keyword parameters for lookups (#101).
• Update schema for roles argument spec to allow specifying attributes on the entrypoint level. These are now also rendered when present (#103).

Bugfixes

• Explicitly declare the sh dependency and limit it to before 2.0.0. Also explicitly declare the dependencies on pydantic, semantic_version, aiohttp, twiggy, and PyYAML (#99).
• Restrict the pydantic dependency to major version 1 (#102).