antsibull-docs 0.1.0

Tools 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.

Running from source

Please note that to run antsibull-docs from source, you need to install some related projects adjacent to the antsibull-docs checkout. More precisely, assuming you checked out the antsibull-docs repository in a directory ./antsibull-docs/, you need to check out the following projects in the following locations:

• antsibull-core needs to be checked out in ./antsibull-core/.

This can be done as follows:

git clone https://github.com/ansible-community/antsibull-core.git
git clone https://github.com/ansible-community/antsibull-docs.git
cd antsibull-docs

Scripts are created by poetry at build time. So if you want to run from a checkout, you'll have to run them under poetry::

python3 -m pip install poetry
poetry install  # Installs dependencies into a virtualenv
poetry run antsibull-docs --help

Note: When installing a package published by poetry, it is best to use pip >= 19.0. Installing with pip-18.1 and below could create scripts which use pkg_resources which can slow down startup time (in some environments by quite a large amount).

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

Creating a new release:

If you want to create a new release::

vim changelogs/fragment/$VERSION_NUMBER.yml  # create 'release_summary:' fragment
antsibull-changelog release --version $VERSION_NUMBER
git add CHANGELOG.rst changelogs
git commit -m "Release $VERSION_NUMBER."
poetry build
poetry publish  # Uploads to pypi.  Be sure you really want to do this

git tag $VERSION_NUMBER
git push --tags
vim pyproject.toml    # Bump the version number
git commit -m 'Update the version number for the next release' pyproject.toml
git push