Package: antsibull-docs
antsibull-docs -- Ansible Documentation Build ScriptsTooling for building Ansible documentation.Script that is here:antsibull-docs - Extracts documentation from ansible pluginsThis also includes aSphinx extensionsphinx_antsibull_extwhich provides a minimal CSS file to render the output ofantsibull-docscorrectly.You can find a list of changes inthe antsibull-docs changelog.Unless otherwise noted in the code, it is licensed under the terms of the GNU
General Public License v3 or, at your option, later.antsibull-docs is covered by theAnsible Code of Conduct.Versioning and compatibilityFrom version 1.0.0 on, antsibull-docs sticks to semantic versioning and aims at providing no backwards compatibility breaking changesto the command line API (antsibull-docs)during a major release cycle. We might make exceptions from this in case of security fixes for vulnerabilities that are severe enough.The current major version is 2.x.y. Development for 2.x.y occurs on themainbranch. 2.x.y mainly differs from 1.x.y by dropping support for Python 3.6, 3.7, and 3.8, and by dropping support for older Ansible/ansible-base/ansible-core versions. See the changelog for details. 1.x.y is still developed on thestable-1branch, but only security fixes, major bugfixes, and other absolutely necessary changes will be backported.We explicitly exclude code compatibility.antsibull-docs is not supposed to be used as a library.The only exception are potential dependencies with other antsibull projects (currently there are none). If you want to use a certain part of antsibull-docs as a library, please create an issue so we can discuss whether we add a stable interface forpartsof the Python code. We do not promise that this will actually happen though.If you are interested in library support for interpreting Ansible markup, please take a look atthe antsibull-docs-parser project.Using the Sphinx extensionInclude it in your Sphinx configurationconf.py::# Add it to 'extensions':
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext']Updating the CSS file for the Sphinx extensionThe CSS filesphinx_antsibull_ext/antsibull-minimal.cssis built fromsphinx_antsibull_ext/css/antsibull-minimal.scssusingSASSandpostcssusingautoprefixerandcssnano.Use the scriptbuild.shinsphinx_antsibull_ext/css/to build the.cssfile from the.scssfile:cd sphinx_antsibull_ext/css/
./build-css.shFor this to work, you need to make sure thatsasscandpostcssare on your path and that the autoprefixer and nanocss modules are installed:# Debian:
apt-get install sassc

# PostCSS, autoprefixer and cssnano require nodejs/npm:
npm install -g autoprefixer cssnano postcss postcss-cliDevelopmentInstall and runnoxto run all tests. That's it for simple contributions!noxwill create virtual environments in.noxinside the checked out project
and install the requirements needed to run the tests there.antsibull-docs depends on the sister antsibull-core and antsibull-docs-parser projects.
By default,noxwill install a development version of these projects from
Github.
If you're hacking on antsibull-core and/or antsibull-docs-parser alongside antsibull-docs,
nox will automatically install the projects from../antsibull-coreand../antsibull-docs-parserwhen running tests if those paths exist.
You can change this behavior through theOTHER_ANTSIBULL_MODEenv var:OTHER_ANTSIBULL_MODE=auto— the default behavior described aboveOTHER_ANTSIBULL_MODE=local— install the projects from../antsibull-coreand../antsibull-docs-parser. Fail if those paths don't exist.OTHER_ANTSIBULL_MODE=git— install the projects from the Github main branchOTHER_ANTSIBULL_MODE=pypi— install the latest versions from PyPITo run specific tests:nox -e testto only run unit tests;nox -e lintto run all linters and formatter;nox -e codeqato runflake8,pylint,reuse lint, andantsibull-changelog lint;nox -e formattersto runisortandblack;nox -e typingto runmypyandpyre.To create a more complete local development env:git clone https://github.com/ansible-community/antsibull-core.gitgit clone https://github.com/ansible-community/antsibull-docs-parser.gitgit clone https://github.com/ansible-community/antsibull-docs.gitcd antsibull-docspython3 -m venv venv. ./venv/bin/activatepip install -e '.[dev]' -e ../antsibull-core -e ../antsibull-docs-parser[...]noxCreating a new release:Runnox -e bump -- <version> <release_summary_message>. This:Bumps the package version insrc/antsibull_docs/__init__.py.Createschangelogs/fragments/<version>.ymlwith arelease_summarysection.Runsantsibull-changelog release --version <version>and adds the changed files to git.Commits with messageRelease <version>.and runsgit tag -a -m 'antsibull-docs <version>' <version>.Runshatch build --clean.Rungit pushto the appropriate remotes.Once CI passes on GitHub, runnox -e publish. This:Runshatch publish;Bumps the version to<version>.post0;Adds the changed file to git and rungit commit -m 'Post-release version bump.';Rungit push --follow-tagsto the appropriate remotes and create a GitHub release.