Tools for building Ansible documentation
Project description
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.
We explicitly exclude code compatibility. antsibull-docs is not supposed to be used as a library. The only exception are dependencies with other antsibull projects (currently, only antsibull itself). 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.
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 pyproject.toml # Make sure version number is correct
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 to X.Y.Z.post0
git commit -m 'Update the version number for the next release' pyproject.toml
git push
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file antsibull_docs-1.11.0.tar.gz.
File metadata
- Download URL: antsibull_docs-1.11.0.tar.gz
- Upload date:
- Size: 252.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.4.1 CPython/3.10.10 Linux/6.2.8-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ff5964475328e1625e73b098dc5ee878a754e32b8987782d74af6643e312c1bc |
|
| MD5 | c0191e750660f289028457fb5a5982ac |
|
| BLAKE2b-256 | bf1a1f604a6e07cf8845f62a3ebeb102f20fee49f772b358ac6f99de54d8638f |
Provenance
File details
Details for the file antsibull_docs-1.11.0-py3-none-any.whl.
File metadata
- Download URL: antsibull_docs-1.11.0-py3-none-any.whl
- Upload date:
- Size: 219.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.4.1 CPython/3.10.10 Linux/6.2.8-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | cc6be4a40526e15139e8c9957fd2170f67ebbe4bf342788792261934a0c9df01 |
|
| MD5 | ddeaadecc7ca79258d46ec656c43b342 |
|
| BLAKE2b-256 | 146d55a5339930e2ebc8f909f1d562ff6be2102339ad523c9e37bc712e9f7511 |
