DocOps at ATIX – the build stage: Adding ‚make html‘ for our style guide to our Documentation Gitlab Pipeline

This short blog series will explain how we automatically test, build, and deploy documentation mostly using vim, git, sphinx, docker, and gitlab. This blog article describes how to use ‚make html‘ and add this make target for our style guide to our internal Gitlab pipeline.

The following is added to the .gitlab-ci.yml to what was shown in the first article.

---
.build:
extends: .build_image
stage: build

build:website:
extends: .build
script:
- make docs_orcharhino_com 2> >(tee errors.txt)
- cat errors.txt
- '[[ $(wc -l < "errors.txt") -le 0 ]]' - tar -czf docs_orcharhino_com.tar.gz -C _build/docs_orcharhino_com/html . artifacts: paths: - docs_orcharhino_com.tar.gz expire_in: "1 day" build:html: extends: .build script: - make html 2> >(tee errors.txt)
- cat errors.txt
- sed -i "/${ACCEPTED_WARNING}/d" errors.txt
- '[[ $(wc -l < "errors.txt") -le 0 ]]' - tar -czf or_bundled_html_docs.tar.gz -C _build/html . artifacts: paths: - or_bundled_html_docs.tar.gz expire_in: "1 day" build:pdf: extends: .build script: - make latexpdf 2> >(tee errors.txt)
- cat errors.txt
- grep WARNING errors.txt > sphinx_errors.txt
- sed -i "/${ACCEPTED_WARNING}/d" sphinx_errors.txt
- '[[ $(wc -l < "sphinx_errors.txt") -le 0 ]]'
- mv _build/latex/orcharhino.pdf orcharhino_admin_guide.pdf
artifacts:
paths:
- orcharhino_admin_guide.pdf
expire_in: "1 day"
...

The build stage extends our .build_image stage.
It has three jobs: building our website, our bundled html, and our pdf version.

The website job simply runs the make target docs_orcharhino_com that has been added to our makefile.
Then, it again displays the errors and counts its lines.
It exits with '0' if there are no errors and with '1' if there’s been one or more errors.
It then creates a .tar.gz file called docs_orcharhino_com.tar.gz containing the output stored in _build/docs_orcharhino_com/html and saves it in the current directory '.'.
The output is declared a Gitlab artifact and discarded after one day.

The html job simply adds a step to remove the error as discussed earlier but is nevertheless very much identical to the first job.

The pdf job also removes the accepted error.
It does not create a .tar.gz file but simply moves the build artifact from _build/latex/orcharhino.pdf to the current directory as orcharhino_admin_guide.pdf.

Disclaimer: We never ever do this.
Because why would we when we can simply have it deployed automatically?!
We really do love automation here at ATIX
Stay tuned for our third and last installment of this series.

Now, we want to also build our style guide which is located in our git repository under style_guide/ with each run:

---
build:style_guide:
  extends: .build
  script:
    - cd style_guide/
    - make html 2> >(tee errors.txt)
    - cat errors.txt
    - '[[ $(wc -l < "errors.txt") -le 0 ]]'
    - tar -czf style_guide_html_docs.tar.gz -C _build/html .
  artifacts:
    paths:
      - style_guide/style_guide_html_docs.tar.gz
    expire_in: "1 day"
...

This job is pretty much identical to our html job with two basic differences:
We change the working directory to style_guide/ in the first step of the script and adapt the file names.

This job results in identical artifacts as the html job which will be deployed in our next blog article.

This post is also available in: Englisch