DocOps at ATIX – Automatically building documentation using Gitlab Pipelines and Sphinx

This short blog series will explain how we automatically test, build, and deploy documentation mostly using vim, git, sphinx, docker, and gitlab.

At ATIX, we are using Sphinx to build our documentation.

There are different make targets to build and test the documentation sources like html, latexpdf, spelling, and linkcheck.
Refer to the Makefile provided by sphinx-quickstart for more information.

We are using git to collectively work on our documentation and to review changes before pushing them to our website and customers.

Gitlab houses our git repository which contains all of our .rst source files and screenshots as well as various ‘DevOps’ functionality.

Every Gitlab pipeline starts a fresh Docker image.
The main advantage is that every Docker container literally runs the same software (as described in our requirements.txt file) to build the documentation.
There are not left over artifacts from the last possibly unsuccessful run and there are no undefined services or packages running.

When I normally write documentation using vim and build it locally, I simply run msd, which is a local alias to make clean && make spelling && make html.
In other words, it removes everything from the _build/ directory, runs a spell checker, and builds the documentation as html.

When making changes -tiny edits or adding new chapters-, we always create a new feature branch which will then be -after being reviewed- merged into master.

Using a Gitlab pipeline allows us to automatically test, build, and deploy our documentation.
It is described in .gitlab-ci.yml in our git repository and runs whenever someone pushes changes to Gitlab.

• The test stage currently only contains one job: run the aforementioned spell checker.
• The build stage builds four artifacts: our style guide and our documentation in three versions: as .pdf document and as html version for our orcharhino .rpm package and as html version for our website with an additional privacy policy page.
• The deploy stage automatically deploys built documentation to an internal http server.

This is great to share a quick preview and to give others the chance to review changes in our built documentation before merging it to master.
Some parts are best viewed in the finished document rather than source files (.rst) and git diffs.
In other words, working with tables in .rst is just delightful. /s

The first article of this series will cover the test stage and add a second job to run the linkcheck make target.
The second article will cover the the build stage.
The third and last article will cover the deploy stage.