Sphinx (reST)#

This is a “sub-pipeline” for building and deploying new changes that have been made to Sphinx files of a specific GitLab project.

Note

Current approach is way more simple than the old one and solely relies on GitLab Pages. If you still curious about how things worked before, you can look though this page and investigate this commit.

Environment#

Name	Necessity	Default value
BPROTO_CI_SPHINX_SOURCE_DIR	Optional	`docs`
BPROTO_CI_SPHINX_WARNINGS_AS_ERRORS	Optional	`false`

Triggers#

All jobs from Sphinx “sub-pipeline” stages are triggered and only if changes have been made to CMake files. Right now such files are detected by these patterns:

docs/**/*
project/**/CMakeLists.txt
project/**/include/**/*.hpp

As you can see from the above list of files pipeline will take into account both types of the project documentation: Doxygen (C++ files) and Sphinx (RST files) documentation.

Jobs overview#

build:docs#

This job is responsible for building HTML documentation from a clean state to make sure there are no unexpected results.

ALLOW FAILURE: Job is not allowed to fail as any failure here means fundamental problems in documentation generation.
ARTIFACTS: Job generate an artifact with a HTML documentation.
DEPENDENCIES: Job doesn’t require artifacts from other jobs and has no dependencies from other stages or jobs.
ENVIRONMENT: A list of all environment variables can be found here.
IMAGES: alpine:3.
STAGE: Build stage.
TRIGGERS: Job is triggered only on merge requests when any file from trigger list is changed.

report:docs#

This is a stage to simplify access to generated HTML files by build:docs.

See also report stage overview from Report stage.

pages#

This stage is responsible for building and deploying static HTML documentation files to the project GitLab Pages.

ALLOW FAILURE: Job is not allowed to fail as any failure here means fundamental problems in documentation generation.
ARTIFACTS: Job generate an artifact with a HTML documentation.
DEPENDENCIES: Job doesn’t require artifacts from other jobs and has no dependencies from other stages or jobs.
ENVIRONMENT: A list of all environment variables can be found here.
IMAGES: alpine:3.
STAGE: Deploy stage.
TRIGGERS: Job is triggered only on CI_DEFAULT_BRANCH when any file from trigger list is changed.