antsibull-docs

What it is and what it does

antsibull-docs is a toolchain for building Ansible project documentation. It provides both a command-line interface (`antsibull-docs`) and a Sphinx extension (`sphinx_antsibull_ext`) that handle the specialized markup and formatting needs of Ansible documentation. The package depends on Sphinx, Jinja2, docutils, and several sister antsibull projects (antsibull-core, antsibull-changelog, antsibull-docs-parser, antsibull-docutils, antsibull-fileutils) to parse, validate, and render Ansible-specific documentation elements.

It is actively maintained and marked as production-stable, supporting Python 3.9 through 3.14. The project explicitly states it is not intended for use as a general library—it is a command-line and Sphinx extension tool for the Ansible documentation ecosystem. The codebase follows semantic versioning from 1.0.0 onward, with the current major version 2.x dropping support for older Python and Ansible versions.

Use it for:

• Building official Ansible project documentation using the antsibull-docs command-line tool
• Integrating Ansible documentation generation into a Sphinx-based documentation pipeline via the sphinx_antsibull_ext extension
• Processing and validating Ansible markup and changelog fragments as part of a release workflow
• Generating formatted HTML or other output formats from Ansible source documentation
• Contributing to Ansible community documentation that relies on this toolchain

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Builds and generates Ansible documentation from source, providing a command-line tool and Sphinx extension for processing Ansible markup into formatted documentation.

Yes, if you are building or maintaining Ansible documentation. The package is actively maintained, has no known vulnerabilities, installs with low friction, and is production-stable. The GPL-3.0-or-later license is appropriate for open-source Ansible projects but requires review for proprietary use. Not recommended for general-purpose documentation building outside the Ansible ecosystem, as it is purpose-built and not designed as a reusable library.

Install

antsibull-docs on PyPI

pip install antsibull-docs

uv add antsibull-docs

poetry add antsibull-docs

Installing antsibull-docs

Before you install

Low friction installation with a pure Python wheel. Active maintenance as of 2026-08-14 with no known vulnerabilities. Requires Python 3.9 or later and pulls in 16 runtime dependencies including Sphinx, Jinja2, and other documentation tooling.

License in practice

Licensed under GPL-3.0-or-later (copyleft). Any derivative work or distribution must comply with GPL v3 terms, including source disclosure obligations. Suitable for open-source projects but requires careful review for proprietary use.

Quickstart

pip install antsibull-docs

from antsibull_docs import __version__
print(__version__)

# Or use the command-line tool:
# antsibull-docs --help

Requires Python 3.9 or later. The package is intended as a command-line tool and Sphinx extension, not as a library for general use.

Verify before relying

• Specific Ansible/ansible-core version compatibility requirements beyond what's documented in the changelog
• Whether the Sphinx extension works with all current Sphinx versions or has version constraints
• Performance characteristics when building large documentation sets

Package facts

Evidence: antsibull_docs-2.26.0-py3-none-any.whl

Tags

More Sphinx packages