- Support portal
- Evaluation Kits and partner products
u-blox Support
- Product documentation
Documentation
- About
- Sustainability
- Partners and Alliances
- Contact
About u-blox
- Investor relations
Investor relations
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:
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.
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.
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.
ROOT_DIR = .
repository
│ gitlab-ci.yml
│
u-locate
│ │ guide.md
│ │ conf.py
│ │ images
│ │ │ image1.png
│ │ │ image2.jpg
ROOT_DIR = ./docs
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