Version latest

Get Started

1. Setup environment variables

In the repository with the documentation, navigate to ‘Settings’ > ‘CI/CD’ and open the accordion ‘Variables’. More information can be found here

setup the following variables:

name

value

description

Protected

Masked

AWS_ACCESS_KEY_ID

provided from admin

Id needed to login to AWS

false

true

AWS_DEFAULT_REGION

eu-central-1

AWS region that contains the bucket

false

false

AWS_SECRET_ACCESS_KEY

provided from admin

Key needed to login to AWS

false

true

S3_BUCKET

provided from admin

name of the AWS bucket that will store the documentation

false

false

ROOT_DIR

?

root directory that contains the documentation source e.g. “.” or “./docs”

false

false

after the setup it should look like this:

Variables

2. Runners

The repository need to have a runner available. In the repository with the documentation, navigate to ‘Settings’ > ‘CI/CD’ and open the accordion ‘Runners’. There needs to be at least one runner listed in of the sections. If there isn’t a runner available, please open a ticket with IT and request a runner to be added to your repository.

3. File Structure

The directory that contains all the documentation files can be configured via the environment variable ‘ROOT_DIR’. Within this folder each documentation needs to be in its own folder. This documentation source may not be nested multiple levels deep. The name of the folder will become part of the URL on which the documentation will be available.

Please add the file .gitlab-ci.yml to the root directory of the repository, and add the following content.

Default  
stages:
  - build
  - deployPreview
  - deploy
  - trigger

build:
  stage: build
  image: python:3.7-alpine
  script:
  - apk update
  - apk add git
  - if [ -d "$ROOT_DIR" ]; then
      echo "$ROOT_DIR does exist.";
    fi
  - pip install -U sphinx
  - pip install myst-parser
  - pip install sphinxcontrib-openapi
  - pip install sphinx-tabs
  - pip install git+https://github.com/u-blox-website/sphinx_minimal_theme
  - for dir in $ROOT_DIR/*/; do
      echo ">> ${dir}";  
      dir=${dir%*/};     
      echo ">> ${dir##*/}";  
      sphinx-build -b singlehtml ${dir} public/${dir##*/} -D html_theme=minimal_theme -D exclude_patterns=versions;
      if [ -d "${dir}/versions" ]; then
        echo ">> ${dir}/versions does exist.";
         for versionsDir in ${dir}/versions/*/; do
          versionsDir=${versionsDir%*/};     
          echo ">> ${versionsDir}";  
          echo ">> ${dir##*/}/versions/${versionsDir##*/}";  
          sphinx-build -b singlehtml ${versionsDir} public/${dir##*/}/versions/${versionsDir##*/}  -D html_theme=minimal_theme;
        done
      fi
    done
  artifacts:
    paths:
    - public

.template: &template
  image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest
  script:
    - echo ">> Running deploy"
    - for dir in public/*/; do
        dir=${dir%*/};     
        echo ">> ${dir}";  
        echo ">> ${dir##*/}";  
        for file in ./public/${dir##*/}/*.html; do
          file=$(basename "$file"); 
          if [[ "$file" != "search.html" && "$file" != "README.html" && "$file" != "genindex.html" ]]; then
            echo "$file"; 
            aws s3 cp ./public/${dir##*/}/"$file" s3://$S3_BUCKET/$AWS_BASE_PATH/${dir##*/}/"$file";
            if [ -d "$ROOT_DIR/${dir##*/}/images" ]; then
              aws s3 cp $ROOT_DIR/${dir##*/}/images s3://$S3_BUCKET/$AWS_BASE_PATH/${dir##*/}/images/ --recursive;
            fi
          fi
        done;
        if [ -d "public/${dir##*/}/versions" ]; then
          echo ">> public/${dir##*/}/versions does exist.";
          for versionsDir in public/${dir##*/}/versions/*/; do
            versionsDir=${versionsDir%*/};     
            echo ">> ${versionsDir}";  
            echo ">> ${dir##*/}/versions/${versionsDir##*/}";  
            for file in ${versionsDir}/*.html; do
              file=$(basename "$file"); 
              if [[ "$file" != "search.html" && "$file" != "README.html" && "$file" != "genindex.html" ]]; then
                echo "$file"; 
                aws s3 cp ${versionsDir}/"$file" s3://$S3_BUCKET/$AWS_BASE_PATH/${dir##*/}/versions/${versionsDir##*/}/"$file";
                if [ -d "$ROOT_DIR/${dir##*/}/versions/${versionsDir##*/}/images" ]; then
                  aws s3 cp $ROOT_DIR/${dir##*/}/versions/${versionsDir##*/}/images s3://$S3_BUCKET/$AWS_BASE_PATH/${dir##*/}/versions/${versionsDir##*/}/images/ --recursive;
                fi
              fi
            done
          done
        fi
      done
    - echo ">> Deployment successful"

 
deployPreview:
  stage: deployPreview
  needs:
    - build
  rules:
    - if: $CI_PIPELINE_SOURCE != "merge_request_event"
  variables:
    AWS_BASE_PATH: "preview"
  <<: *template

deploy:
  stage: deploy
  needs:
    - build
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
  variables:
    AWS_BASE_PATH: "production"
  <<: *template

trigger:
  stage: trigger
  needs:
    - deploy
  script:
    - apk add --no-cache curl  # Install curl
    - curl -X POST -d '{}' https://api.netlify.com/build_hooks/66d438673b06cc0644162d5e
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

In each documentation folder, you’ll also need to add a file named conf.py which will contain configuration for generating the documentation. It’s content depends on whether you are using Markdown or Restructured Text. Please see below for more details.

All images in a documentation need to be stored in the folder images in the main folder of the documentation.

Example 1

ROOT_DIR = .

Default  
repository
│   gitlab-ci.yml
│
u-locate
│   │   guide.md
│   │   conf.py
│   │   images
│   │   │   image1.png
│   │   │   image2.jpg


Example 2

ROOT_DIR = ./docs

Default  
repository
│   gitlab-ci.yml
│
docs
│   u-locate
│   │   guide.md
│   │   conf.py
│   │   images
│   │   │   image1.png
│   │   │   image2.jpg
│   u-center
│   │   manual.md
│   │   conf.py
│   │   images
│   │   │   image1.png
│   │   │   image2.jpg

Last updated: Feb 3, 2025
Need help?Contact Support
Questions?Contact us