04. 03. 2025
Automation, DevOps, Service Management
26. 06. 2025
Davide Sbetti
Automation, Development, Documentation, NetEye
Building (and Customizing) Documentation for Your Ansible Collections
In NetEye, we use Ansible to automate many different tasks in an idempotent way, ranging from the first installation of the system to updates and upgrades.
Ansible already comes with many built-in useful modules to manage files, perform HTTPS requests and much more. Furthermore, various Ansible Collections have been developed by the community to address specific use cases and interact, for example, with more specific software such as MySQL DBMS.
However, it’s not always possible to find a collection or built-in module which satisfies all your requirements, and so to also simplify the life of the developers who work on NetEye, we’ve developed inside the R&D Team some custom Ansible Collections that we use in the management of NetEye installations, such as a collection to interact with PCS, and one to handle checkpoints during updates and upgrades.
Having the collections is great and for sure it helps us in writing Ansible playbooks which are more compact, have less duplicate code, and perform idempotent actions.
Clearly having the collections is not enough, and it’s also important to allow other developers to quickly understand what they are and how to use them in an effective way, to avoid slowing down the development process.
For this reason, we decided to build and publish internally a little customized version of the Ansible documentation for just our collections! Let’s see how 😀
Building the Ansible Documentation
Ansible, in its default format, embeds the documentation of each module inside the module code itself, at the beginning of the file, as can be seen for example in the blockinfile module. The documentation, written in RST format, may also be followed by a section reporting some usage examples.
How can we generate an actual docsite from this documentation?
Well, with the antsibull-docs tool of course!
The tool is designed to build the documentation of the Ansible collections to an HTML website to expose them. It works quite easily, it’s just necessary to install it in a Python virtualenv through pip, and run it specifying, in our case, for which collections we would like to build the documentation. Since all our collections are part of the neteye namespace and the tool allows globs, it becomes quite easy to restrict the scope to just our collections.
An example of the execution, inside a NetEye environment, can be similar to the following:
VENV="/tmp/test-neteye-ansible-doc-build-venv"
BUILD_DIR="/tmp/test-neteye-ansible-doc-build-venv"
# Create the build dir
mkdir -p "$BUILD_DIR"
# Create a python venv
python3 -m venv "$VENV"
# Activate it
source "$VENV/bin/activate"
# Install the requirements
pip install antsibull-docs
# Generate the sphinx build structure
antsibull-docs sphinx-init --use-current \
--dest-dir "$BUILD_DIR" neteye.*
Now with this, we’ve prepared the environment to build the documentation of our collections.
What does this mean?
Well, that in our BUILD_DIR, we can now find the basic structure, in terms of RST files, for the final documentation. This is because the antsibull-docs sphinx-init command prepares the directory with a basic configuration for Sphinx, and an entry point for the documentation under index.rst.
And, as mentioned by the official documentation, after having prepared the directory structure and basic configuration, it’s possible to just install the missing requirements for the building process and run the build.sh script that we find inside the BUILD_DIR to obtain, under the build/html folder, the final HTML files.
cd "$BUILD_DIR"
pip install -r requirements.txt
./build.sh
The result? Well, a beautiful documentation website!
Customizing the docsite
As we can see, the docsite comes with the default Ansible theme and annotations. The antsibull-docs tool exposes some options to allow a bit of customization, but not all aspects can actually be controlled with those options. However, the tool uses Sphinx under the hood for the docsite generation, and we are already familiar with the Sphinx framework.
For this reason, we decided to provide a custom conf.py which, besides customizing some labels such as the title on the upper left, the copyright notice and the introductory text, also specifies an additional folder with some static content to provide a custom CSS and Javascript for… some little tweaks (yes, try to spot all the differences 😅)!
html_static_path = ["_static"]
html_css_files = ["css/neteye.css"]
html_js_files = ["js/neteye.js"]
During the building process of the docsite, our custom conf.py overrides the one automatically generated by antsibull-docs, leading to the following result:
The Importance of… Extra Documentation!
By default, the documentation for each collection is divided up by plugin (also known as module), and displays the one written inside that module’s source code.
However, a very nice feature is the possibility to add a folder named docsite inside the doc folder of each collection that contains the following elements:
- An
rstsubfolder containing documentation in the form of RST files - A YAML file named
extra-docs.ymlwhich specifies additional sections for the menu on the left side of the collection, and imports some of the RST files defined in the folder mentioned above:
sections:
- title: How To Guides
toctree:
- guide1
- guide2
For us this was quite important, since it allowed us, for example, to specify a How To Guides section for the upgrade manager collection which contains some more documentation with more detailed examples of how to use it in various cases.
And now that we’re satisfied with the resulting documentation, we decided to expose the documentation using an nginx-unprivileged Docker image and automate the building process with a BuildConfig on our OpenShift cluster, for an always up-to-date documentation of our collections!
These Solutions are Engineered by Humans
Did you find this article interesting? Are you an “under the hood” kind of person? We’re really big on automation and we’re always looking for people in a similar vein to fill roles like this one as well as other roles here at Würth Phoenix.
Davide Sbetti
Hi! I'm Davide and I'm a Software Developer with the R&D Team in the "IT System & Service Management Solutions" group here at Würth Phoenix. IT has been a passion for me ever since I was a child, and so the direction of my studies was...never in any doubt! Lately, my interests have focused in particular on data science techniques and the training of machine learning models.
Author
Latest posts by Davide Sbetti
31. 03. 2025
Development, DevOps, NetEye
Reducing the NetEye ISO Size: How to Carefully Choose the Right Packages!