antsibull-docs

2.24.0 verified Mon Apr 27 auth: no python

Tools for building Ansible documentation, including collection docs, man pages, and docsite. Current version 2.24.0, Python >=3.9 required. Release cadence: ad-hoc, roughly every 2-4 months.

pip install antsibull-docs

Common errors

error ModuleNotFoundError: No module named 'antsibull_docs' ↓

cause antsibull-docs not installed in the current Python environment.

fix

pip install antsibull-docs

error TypeError: expected str, bytes or os.PathLike object, not NoneType ↓

cause Environment variable ANSIBLE_COLLECTIONS_PATH is not set or is None.

fix

Set ANSIBLE_COLLECTIONS_PATH to the directory containing Ansible collections, or pass --collection-dir explicitly.

Warnings

breaking antsibull-docs v2 reworked the CLI and configuration. Scripts using the old v1 CLI flags or import paths will break. ↓

fix Migrate to the new CLI; see https://github.com/ansible-community/antsibull-docs/blob/main/CHANGELOG.rst for details.

deprecated The 'antsibull-docs collection' subcommand's '--use-classic-output' option is deprecated in v2.16+ and will be removed. ↓

fix Use the new output format; remove the flag.

gotcha Running antsibull-docs from a virtualenv without required Ansible collections installed will cause runtime errors. docs-build expects collections under a specific path. ↓

fix Install the collections you intend to document (e.g., via ansible-galaxy) and set ANSIBLE_COLLECTIONS_PATH or use the --collection-dir flag.

Imports

AnsibleDocsCli
wrong
```
from antsibull_docs import AnsibleDocsCli
```
correct
```
from antsibull_docs.cli import AnsibleDocsCli
```
AnsibleDocsCli is in the cli submodule, not directly in antsibull_docs

CollectionLinters

wrong

from antsibull_docs.linters import CollectionLinters

correct

from antsibull_docs.lint import CollectionLinters

Module is 'lint' not 'linters'

Quickstart

Minimal usage: import and instantiate the CLI. For actual doc generation, invoke with subcommands like 'collection' or 'manpage'.

from antsibull_docs.cli import AnsibleDocsCli
cli = AnsibleDocsCli()
# Run the CLI; for example, to generate collection docs:
# cli.run(['collection', '--help'])