{"id":20930,"library":"antsibull-docs","title":"antsibull-docs","description":"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.","status":"active","version":"2.24.0","language":"python","source_language":"en","source_url":"https://github.com/ansible-community/antsibull-docs","tags":["ansible","documentation","docs","collection"],"install":[{"cmd":"pip install antsibull-docs","lang":"bash","label":"Standard install"}],"dependencies":[{"reason":"Core utilities for antsibull-docs; often installed together","package":"antsibull-core","optional":false},{"reason":"Async I/O helpers","package":"asyncio-helper","optional":false},{"reason":"For building docsites","package":"sphinx","optional":true}],"imports":[{"note":"AnsibleDocsCli is in the cli submodule, not directly in antsibull_docs","wrong":"from antsibull_docs import AnsibleDocsCli","symbol":"AnsibleDocsCli","correct":"from antsibull_docs.cli import AnsibleDocsCli"},{"note":"Module is 'lint' not 'linters'","wrong":"from antsibull_docs.linters import CollectionLinters","symbol":"CollectionLinters","correct":"from antsibull_docs.lint import CollectionLinters"}],"quickstart":{"code":"from antsibull_docs.cli import AnsibleDocsCli\ncli = AnsibleDocsCli()\n# Run the CLI; for example, to generate collection docs:\n# cli.run(['collection', '--help'])","lang":"python","description":"Minimal usage: import and instantiate the CLI. For actual doc generation, invoke with subcommands like 'collection' or 'manpage'."},"warnings":[{"fix":"Migrate to the new CLI; see https://github.com/ansible-community/antsibull-docs/blob/main/CHANGELOG.rst for details.","message":"antsibull-docs v2 reworked the CLI and configuration. Scripts using the old v1 CLI flags or import paths will break.","severity":"breaking","affected_versions":">=1.0,<2.0 -> 2.x"},{"fix":"Use the new output format; remove the flag.","message":"The 'antsibull-docs collection' subcommand's '--use-classic-output' option is deprecated in v2.16+ and will be removed.","severity":"deprecated","affected_versions":">=2.16,<3.0"},{"fix":"Install the collections you intend to document (e.g., via ansible-galaxy) and set ANSIBLE_COLLECTIONS_PATH or use the --collection-dir flag.","message":"Running antsibull-docs from a virtualenv without required Ansible collections installed will cause runtime errors. docs-build expects collections under a specific path.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"pip install antsibull-docs","cause":"antsibull-docs not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'antsibull_docs'"},{"fix":"Set ANSIBLE_COLLECTIONS_PATH to the directory containing Ansible collections, or pass --collection-dir explicitly.","cause":"Environment variable ANSIBLE_COLLECTIONS_PATH is not set or is None.","error":"TypeError: expected str, bytes or os.PathLike object, not NoneType"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}