{"id":30358,"date":"2020-07-23T07:10:33","date_gmt":"2020-07-23T05:10:33","guid":{"rendered":"https:\/\/orcharhino.com\/ressourcen\/blog\/docops-at-atix-automatically-building-documentation-using-gitlab-pipelines-and-sphinx-2\/"},"modified":"2026-03-05T14:04:41","modified_gmt":"2026-03-05T13:04:41","slug":"docops-at-atix-automatically-building-documentation-using-gitlab-pipelines-and-sphinx-2","status":"publish","type":"post","link":"https:\/\/orcharhino.com\/en\/resources\/blog\/docops-at-atix-automatically-building-documentation-using-gitlab-pipelines-and-sphinx-2\/","title":{"rendered":"DocOps at ATIX \u2013 Automatically building documentation using Gitlab Pipelines and Sphinx"},"content":{"rendered":"\n

This short blog series will explain how we automatically test, build, and deploy documentation mostly using vim, git, sphinx, docker, and gitlab.<\/em><\/p>\n\n\n\n

At\u00a0ATIX<\/a>, we are using\u00a0Sphinx\u00a0<\/a>to build our\u00a0documentation<\/a>.<\/p>\n\n\n\n

\n
<\/div>\n\n\n\t\t
\n\t\t\t\t
\n\t\t\t\t\t
\n\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\"img_whitepaper_digital_sovereignty\"\t\t\t\t\t\t\t\t<\/a>\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t

Who controls your IT – you or your dependencies?<\/strong><\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t

\n\t\t\t\t\t\t\t\t\t

Read the free white paper to find out how to identify critical dependencies, make your infrastructure resilient and regain full control over operations, updates and automation.<\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t

\n\t\t\t\t\t\t\t\t\t

Download whitepaper now<\/strong><\/a><\/p>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\n\n\n\n

<\/div>\n<\/div>\n\n\n\n

There are different\u00a0make targets<\/code>\u00a0to build and test the documentation sources like\u00a0html<\/code>,\u00a0latexpdf<\/code>,\u00a0spelling<\/code>, and\u00a0linkcheck<\/code>.
Refer to the\u00a0Makefile<\/code>\u00a0provided by\u00a0sphinx-quickstart<\/a><\/code>\u00a0for more information.<\/p>\n\n\n\n

We are using\u00a0git<\/a>\u00a0<\/code>to collectively work on our documentation and to review changes before pushing them to our website and customers.<\/p>\n\n\n\n

Gitlab\u00a0<\/a>houses our git repository which contains all of our\u00a0.rst<\/code>\u00a0source files and screenshots as well as various \u201aDevOps\u2018 functionality.<\/p>\n\n\n\n

Every Gitlab pipeline starts a fresh\u00a0Docker<\/a>\u00a0image.
The main advantage is that every Docker container literally runs the same software (as described in our\u00a0requirements.txt<\/code>\u00a0file) 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.<\/p>\n\n\n\n

When I normally write documentation using\u00a0vim<\/a>\u00a0and build it locally, I simply run\u00a0msd<\/code>, which is a local alias to\u00a0make clean && make spelling && make html<\/code>.
In other words, it removes everything from the\u00a0_build\/<\/code>\u00a0directory, runs a spell checker, and builds the documentation as html.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

Using a Gitlab pipeline allows us to automatically test, build, and deploy our documentation.
It is described in\u00a0.gitlab-ci.yml<\/code>\u00a0in our git repository and runs whenever someone pushes changes to Gitlab.<\/p>\n\n\n\n