antsibull-docs – Building Ansible documentation¶
This package provides tooling for validating and building Ansible documentation. It mainly consists of a CLI tool, antsibull-docs
, and a Sphinx extension. The main output format are reStructured Text (RST) files for consumption by Sphinx.
Collection maintainers and authors should look at the Creating a collection docsite section of this docsite.
antsibull-docs is covered by the Ansible Code of Conduct.
antsibull-docs
subcommands¶
The main CLI tool, antsibull-docs
, has multiple subcommands:
- The
devel
andstable
subcommands are used for building the official Ansible docsites at docs.ansible.com/ansible/devel and docs.ansible.com/ansible/latest. - The
current
andcollection
subcommands are used for building docsites for individual collections. - The
plugin
andcollection-plugins
subcommands are used for rendering documentation for individual (or all) plugins, modules, or roles. - The
lint-collection-docs
andlint-core-docs
subcommands are used for linting collection and ansible-core documentation. The former is described in more detail in Creating a collection docsite. - The
sphinx-init
subcommmand is used for setting up a Sphinx-based collection docsite. This is described in more detail in Creating a collection docsite.
Using the Sphinx extension¶
The sphinx_antsibull_ext
Sphinx extension provides minimal CSS and several roles used by the written RST files to render the documentation correctly. To use it, include it in your Sphinx configuration conf.py
:
# Add it to 'extensions':
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext']
It is possible to configure the color scheme used by the extension using the antsibull_ext_color_scheme
configuration. Currently, the following values are supported:
default
: the default colors.default-dark
: a dark color scheme.default-autodark
: the default colors or the dark colors, depending on aprefers-color-scheme
media query.none
: define no colors. You can use this if you want to override all colors by your own definition and thus have no need for the default colors to be included.
The default color scheme can be found in src/sphinx_antsibull_ext/css/colors-default.scss. See the MDN page on using CSS custom properties for information on how the color definitions work.
Please note that the color scheme only works for HTML output. The colors for LaTeX / PDF output are hardcoded and currently cannot be modified.
License¶
Unless otherwise noted in the code, it is licensed under the terms of the GNU General Public License v3 or, at your option, later. See LICENSES/GPL-3.0-or-later.txt for a copy of the license.
The repository follows the REUSE Specification for declaring copyright and
licensing information. The only exception are changelog fragments in changelog/fragments/
.