At ATIX, we are using Sphinx to build our documentation.
There are different
make targets to build and test the documentation sources like
Refer to the
Makefile provided by
sphinx-quickstart for more information.
We are using
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
- 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
The third and last article will cover the