bcoca / antsibull-docs

Tooling for building Ansible documentation

antsibull-docs -- Ansible Documentation Build Scripts

Tooling for building Ansible documentation.

Script that is here:

• antsibull-docs - Extracts documentation from ansible plugins

This also includes a Sphinx extension sphinx_antsibull_ext which provides a minimal CSS file to render the output of antsibull-docs correctly.

You can find a list of changes in the 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 the Ansible Code of Conduct.

Versioning and compatibility

From version 1.0.0 on, antsibull-docs sticks to semantic versioning and aims at providing no backwards compatibility breaking changes to 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 the main branch. 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 the stable-1 branch, 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 for parts of 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 at the antsibull-docs-parser project.

Using the Sphinx extension

Include it in your Sphinx configuration conf.py::

# Add it to 'extensions':
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext']

Updating the CSS file for the Sphinx extension

The CSS file sphinx_antsibull_ext/antsibull-minimal.css is built from sphinx_antsibull_ext/css/antsibull-minimal.scss using SASS and postcss using autoprefixer and cssnano.

Use the script build.sh in sphinx_antsibull_ext/css/ to build the .css file from the .scss file:

cd sphinx_antsibull_ext/css/
./build-css.sh

For this to work, you need to make sure that sassc and postcss are 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-cli

Development

Install and run nox to run all tests. That's it for simple contributions! nox will create virtual environments in .nox inside 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, nox will 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-core and ../antsibull-docs-parser when running tests if those paths exist. You can change this behavior through the OTHER_ANTSIBULL_MODE env var:

• OTHER_ANTSIBULL_MODE=auto — the default behavior described above
• OTHER_ANTSIBULL_MODE=local — install the projects from ../antsibull-core and ../antsibull-docs-parser. Fail if those paths don't exist.
• OTHER_ANTSIBULL_MODE=git — install the projects from the Github main branch
• OTHER_ANTSIBULL_MODE=pypi — install the latest versions from PyPI

To run specific tests:

1. nox -e test to only run unit tests;
2. nox -e lint to run all linters and formatter;
3. nox -e codeqa to run flake8, pylint, reuse lint, and antsibull-changelog lint;
4. nox -e formatters to run isort and black;
5. nox -e typing to run mypy and pyre.

To create a more complete local development env:

git clone https://github.com/ansible-community/antsibull-core.git
git clone https://github.com/ansible-community/antsibull-docs-parser.git
git clone https://github.com/ansible-community/antsibull-docs.git
cd antsibull-docs
python3 -m venv venv
. ./venv/bin/activate
pip install -e '.[dev]' -e ../antsibull-core -e ../antsibull-docs-parser
[...]
nox

Creating a new release:

1. Run nox -e bump -- <version> <release_summary_message>. This:
   • Bumps the package version in src/antsibull_docs/__init__.py.
   • Creates changelogs/fragments/<version>.yml with a release_summary section.
   • Runs antsibull-changelog release --version <version> and adds the changed files to git.
   • Commits with message Release <version>. and runs git tag -a -m 'antsibull-docs <version>' <version>.
   • Runs hatch build --clean.
2. Run git push to the appropriate remotes.
3. Once CI passes on GitHub, run nox -e publish. This:
   • Runs hatch publish;
   • Bumps the version to <version>.post0;
   • Adds the changed file to git and run git commit -m 'Post-release version bump.';
4. Run git push --follow-tags to the appropriate remotes and create a GitHub release.