Render with Gitlab CI¶
This page
Downloads¶
Example-1.gitlab-ci.yml¶
Download Example-1.gitlab-ci.yml
File content:
stages:
- docs
- deploy
docu-build:
stage: docs
image:
name: t3docs/render-documentation:v2.3.0
entrypoint: [""]
before_script:
# Copy the content of the current folder to /PROJECT
# This is needed, because the path is hardcoded and cannot be configured in v2.3.0
- cp -a ${CI_PROJECT_DIR}/. /PROJECT
# If you set -c resultdir to some path, but you need to make sure the folder exists beforehand
- mkdir -p ${CI_PROJECT_DIR}/Documentation-GENERATED-temp
# Alternatively, symlink the /RESULT to somewhere inside the ${CI_PROJECT_DIR} since Gitlab
# will not accept artiacts from outside of this path
# - ln -s /RESULT ${CI_PROJECT_DIR}/Documentation-built
script:
# Make sure to be in /ALL/venv, else this will not work!
- cd /ALL/venv
# Run the script without cache and set the resultdir to Documentation-GENERATED-temp
- /ALL/Menu/mainmenu.sh makehtml-no-cache -c resultdir ${CI_PROJECT_DIR}/Documentation-GENERATED-temp
rules:
- changes:
- Documentation
when: always
- when: never
artifacts:
paths:
- ${CI_PROJECT_DIR}/Documentation-GENERATED-temp
deploy:
image: cabag/rsync
stage: deploy
dependencies:
- docu-build
script:
- echo "Deploy content..."
Example-2.gitlab-ci.yml¶
Download Example-2.gitlab-ci.yml
File content:
# Taken: from issue #128
# Title: "add .gitlab-ci.yml for docker builds in local instances"
# URL..: https://github.com/t3docs/docker-render-documentation/issues/128
# by...: https://github.com/kaystrobach
stages:
- test
- build docker image
- push docker image
- vulnerability scan
build:
stage: build docker image
image:
name: gcr.io/kaniko-project/executor:v1.8.1-debug
entrypoint: [ "" ]
script:
- /kaniko/executor
--context "${CI_PROJECT_DIR}"
--dockerfile "${CI_PROJECT_DIR}/Dockerfile"
--destination "${CI_REGISTRY_IMAGE}"
--no-push
--tarPath docker-image.tar
needs: [ ]
artifacts:
expire_in: 7 days
paths:
- docker-image.tar
when: on_success
except:
variables:
- $CD_DOCKER_BUILD_IGNORE
determine tag:
stage: push docker image
rules:
- if: $CD_DOCKER_PUSH_IGNORE
when: never
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
variables:
DOCKER_IMAGE_TAG: "latest"
- if: $CI_COMMIT_BRANCH
variables:
DOCKER_IMAGE_TAG: "branch-${CI_COMMIT_BRANCH}-latest"
- if: $CI_COMMIT_TAG
variables:
DOCKER_IMAGE_TAG: "${CI_COMMIT_TAG}"
script:
- echo "DOCKER_IMAGE_TAG=${DOCKER_IMAGE_TAG}" >> dockerImage.env
needs: [ ]
artifacts:
when: always
expire_in: 7 days
paths:
- dockerImage.env
reports:
dotenv: dockerImage.env
push:
stage: push docker image
image:
name: gcr.io/go-containerregistry/crane/debug:v0.10.0
entrypoint: [ "" ]
rules:
- if: $CD_DOCKER_PUSH_IGNORE
when: never
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: on_success
- if: $CI_COMMIT_TAG
when: on_success
- when: never
script:
- crane auth login -u ${CI_REGISTRY_USER} -p ${CI_REGISTRY_PASSWORD} ${CI_REGISTRY}
- crane push docker-image.tar ${CI_REGISTRY_IMAGE}:${DOCKER_IMAGE_TAG}
needs:
- build
- determine tag
dependencies:
- determine tag
- build
retry: 2
push branch image:
stage: push docker image
image:
name: gcr.io/go-containerregistry/crane/debug:v0.10.0
entrypoint: [ "" ]
rules:
- if: $CD_DOCKER_PUSH_IGNORE
when: never
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: never
- if: $CI_COMMIT_BRANCH
when: on_success
- when: never
script:
- crane auth login -u ${CI_REGISTRY_USER} -p ${CI_REGISTRY_PASSWORD} ${CI_REGISTRY}
- crane push docker-image.tar ${CI_REGISTRY_IMAGE}:${DOCKER_IMAGE_TAG}
needs:
- build
- determine tag
dependencies:
- determine tag
- build
environment:
name: branch-docker-image/${CI_COMMIT_BRANCH}
on_stop: delete branch image
retry: 2
delete branch image:
stage: push docker image
image: debian:11.4-slim
variables:
GIT_STRATEGY: none
rules:
- if: $CD_DOCKER_PUSH_IGNORE
when: never
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: never
- if: $CI_COMMIT_BRANCH
when: manual
allow_failure: true
- when: never
before_script:
- apt update && apt install -y curl
- curl -L https://github.com/genuinetools/reg/releases/download/v0.16.1/reg-linux-amd64 > /bin/reg
- chmod +x /bin/reg
script:
- /bin/reg rm -d -u ${CI_REGISTRY_USER} -p ${CI_REGISTRY_PASSWORD} ${CI_REGISTRY_IMAGE}:${DOCKER_IMAGE_TAG}
needs:
- build
- determine tag
dependencies:
- determine tag
environment:
name: branch-docker-image/${CI_COMMIT_BRANCH}
action: stop
retry: 2
Requirements¶
Make sure you have a running Gitlab CI pipeline and a runner is assigned to your project.
Basic Configuration¶
This basic configuration should cover the needs of most users as it will expose the content to the public folder. If you already have pages configured, you'll just need this.
pages:
stage: test
image:
name: t3docs/render-documentation:develop
entrypoint: [""]
script:
# cleanup
- rm -rf $CI_PROJECT_DIR/public
- mkdir -p $CI_PROJECT_DIR/public
- mkdir -p /RESULT
- rm -rf /PROJECT
- ln -s $CI_PROJECT_DIR /PROJECT
# switch to venv to ensure environment fits
- cd /ALL/venv/
# execute
- /ALL/Menu/mainmenu.sh makeall -c jobfile /$CI_PROJECT_DIR/Documentation/jobfile.json
# publish result
- cp -r /RESULT/Result/project/0.0.0/* $CI_PROJECT_DIR/public
# fix problem with index.html vs Index.html
- if [ ! -f $CI_PROJECT_DIR/public/index.html ]; then echo "<meta http-equiv='refresh' content='0;url=Index.html'>" > $CI_PROJECT_DIR/public/index.html; fi
artifacts:
paths:
- public
tags:
- docker
Advanced Configuration¶
Advanced users may want to tweek the configuration somewhat for various reasons. Here's an example of how to change the default script to specific needs.
docu:
stage: test
image:
name: t3docs/render-documentation:v2.3.0
entrypoint: [""]
before_script:
# Copy the content of the current folder to /PROJECT
# This is needed, because the path is hardcoded and cannot be configured in v2.3.0
- cp -a ${CI_PROJECT_DIR}/. /PROJECT
# Alternatively you can symlink the folder, too
# - rm -rf /PROJECT && ln -s ${CI_PROJECT_DIR} /PROJECT
# If you set -c resultdir to some path, but you need to make sure the folder exists beforehand
- export resultdir=${CI_PROJECT_DIR}/Documentation-GENERATED-temp
- mkdir -p ${CI_PROJECT_DIR}/Documentation-GENERATED-temp
# Alternatively, symlink the /RESULT to somewhere inside the ${CI_PROJECT_DIR} since Gitlab
# will not accept artiacts from outside of this path
# - ln -s /RESULT ${CI_PROJECT_DIR}/Documentation-built
script:
# Make sure to be in /ALL/venv, else this will not work!
- cd /ALL/venv
# Execute
- /ALL/Menu/mainmenu.sh makehtml-no-cache -c resultdir $resultdir
# fix problem with index.html vs Index.html
- if [ ! -f $CI_PROJECT_DIR/$resultdir/Result/project/0.0.0/index.html ]; then echo "<meta http-equiv='refresh' content='0;url=Index.html'>" > $CI_PROJECT_DIR/$resultdir/Result/project/0.0.0//index.html; fi
# Only available for Gitlab Runners 12.3+! Run the script only if something changed in the documentation
rules:
- changes:
- Documentation
when: always
- when: never
artifacts:
paths:
- ${CI_PROJECT_DIR}/Documentation-GENERATED-temp/
Additonal information¶
Terms: RenderDocumentation, TCT, toolchain
Here is some additional information you may be looking for.
Note: TCT is our toolchain runner. It runs
RenderDocumentation which is our toolchain.
dockrun_t3rd or docker run?¶
Terms: dockrun
The dockrun_t3rd function is just a helper tool to help assembling the final
Docker command. If you are not using this helper write the explicite form in
the examples below. The explicite form is:
# instead of dockrun_t3rd write:
OUR_IMAGE_TAG=v2.3.0 <-- for example
OUT_IMAGE_TAG=develop <-- adapt
docker run --rm t3docs/render-documentation:$OUR_IMAGE_TAG
Parameters of the toolchain "RenderDocumentation"¶
Only the toolchain itself knows which parameters and options it takes. So we have to run the toolchain and ask for that information like so:
dockrun_t3rd tct run RenderDocumentation --toolchain-help
You should be seeing something like this:
➜ ~ dockrun_t3rd tct run RenderDocumentation --toolchain-help
Usage: tct run [OPTIONS] RenderDocumentation
Run the toolchain 'RenderDocumentation'.
Options:
-c, --config KEY VALUE Define or override config key-value pair
(repeatable)
-n, --dry-run Perform a trial run with no changes made.
--toolchain-help Tell the toolchain to display its help text.
The toolchain should do that and then exit.
-T, --toolchain-action ACTION Tell the toolchain to execute the action.
(repeatable)
--help Show this message and exit.
Toolchain options:
-T clean Let the toolchain delete prior builds, then exit.
-T help Show toolchain help and e exit.
-T unlock Remove possible lock and exit.
-T version Show toolchain version and exit.
-c makedir PATH/TO/MAKEDIR Required! The path to the 'make' folder.
-c resultdir PATH/TO/MAKEDIR Optional. The path to the
'Documentation-GENERATED-temp' folder. Must
exist if specified.
-c buildsettings PATH/TO/FILE If specified, this file overrides the normal
makedir/buildsettings.sh
-c overrides PATH/TO/FILE If specified, this file is used instead of the
normal makedir/Overrides.cfg
-c rebuild_needed 1 Force rebuild regardless of checksum
-c make_singlehtml 1 yes (default)
-c make_singlehtml 0 no
-c make_latex 1 yes! Make LaTeX and PDF(default)
-c make_latex 0 no
-c make_package 1 yes (default)
-c make_package 0 no
-c talk 0 run quietly
-c talk 1 talk just the minimum (default)
-c talk 2 talk more
-c jobfile PATH/TO/JOBFILE.JSON pass in all kind of settings
-c email_user_to_instead "email1,email2,..." instead of real user
-c email_user_cc "email1,email2,..." additionally, publicly
-c email_user_bcc "email1,email2,..." additionally, secretly
-c email_user_send_to_admin_too 1 like it says
➜
About Documentation/jobfile.json¶
Terms: jobfile
For container version v2.3.0 or newer
This file is very powerful and will override almost all settings that have been
made before in the process. You can use it only on machines where you are the
administrator or operator yourself. The rendering of official documentation for
the TYPO3 docs server is done with a jobfile that you cannot control.
The jobfile.json file is maintained with your project OUTSIDE the
container. But it is used at run time WITHIN the container. So when you start
the container and pass the file location you have to specify one that's valid
WITHIN the container.
A good choice to place the file is in
YOUR-PROJECT/Documentation/jobfile.json. In that case you would add
-c jobfile /PROJECT/Documentation/jobfile.json to the Docker run command.
Another obvious place would be
YOUR-PROJECT/Documentation-GENERATED-temp/jobfile.json, especially if
the jobfile gets generated somehow. In that case the command line needs to have
-c jobfile /RESULT/Documentation/jobfile.json.
The name jobfile is just a - useful - convention. It could as well be a
json file named abc.json, for which you would write
-c jobfile /PROJECT/Documentation/abc.json.
As of container version v2.3.0 we have the following. This will probably be extended with newer versions. Some settings are postfixed with '_DISABLED' which can be removed to activate them.
- Minimal, no operation
{ "Overrides_cfg": { "comment": "This section goes into conf.py, which is the Sphinx config file", "general": { } }, "tctconfig": { "comment": "This sections defines how the toolchain behaves", }, "dockrun_t3rd": { "comment_1": "This can be used on the local machine to define the build call", "comment_2": "set action to makehtml, makehtml-no-cache, makeall, makeall-no-cache", "action": "makehtml-no-cache", "jobfile_option": " -c jobfile /PROJECT/Documentation/jobfile.json" } }
- Extensive
{ "Overrides_cfg": { "comment": "This section goes into conf.py, which is the Sphinx config file", "general": { "html_theme": "t3SphinxThemeRtd", "keep_warnings": 0, "language": "en", "html_logo_DISABLED": "../TheProject/Documentation/_static/logo.svg", "html_css_files": ["css/my-extra.css"], "html_static_path_DISABLED": ["../TheProject/Documentation/_static"], "nitpicky": false, "nitpick_ignore": [["py:class", "type"]], "project": "The Project", "release": "9.8.7", "rst_epilog": "", "rst_prolog_DISABLED": "\n.. This is 'Includes.txt'. It is included at the very top of each and\n every ReST source file in THIS documentation project (= manual).\n\n.. role:: aspect (emphasis)\n.. role:: html(code)\n.. role:: js(code)\n.. role:: php(code)\n.. role:: typoscript(code)\n.. role:: ts(typoscript)\n :class: typoscript\n\n.. highlight:: php\n.. default-role:: code\n", "version": "9.8", "zzz": 0 } }, "tctconfig": { "comment": "This sections defines how the toolchain behaves", "activateLocalSphinxDebugging": 0, "disable_include_files_check": 1, "force_rebuild_needed": 1, "make_html": 1, "make_latex": 0, "make_pdf": 0, "make_singlehtml": 0, "rebuild_needed": 1, "replace_static_in_html": 1, "reveal_exitcodes": 1, "reveal_milestones": 1, "talk": 1, "try_pdf_build_from_published_latex": 1 }, "dockrun_t3rd": { "comment_1": "This can be used on the local machine to define the build call", "comment_2": "set action to makehtml, makehtml-no-cache, makeall, makeall-no-cache", "action": "makehtml-no-cache", "jobfile_option": " -c jobfile /PROJECT/Documentation/jobfile.json" } }
"Edit on GitLab" button with the sphinx_rtd_theme¶
The corresponding html template looks like this:
<a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
Edit a single file¶
Have something like this in your jobfile.json file:
{
"Overrides_cfg": {
"general": {
"html_theme": "sphinx_rtd_theme",
"html_context": {
"display_gitlab": true,
"gitlab_host": "gitlab.com",
"gitlab_user":"GITLAB_USER",
"gitlab_repo": "GITLAB_REPO",
"theme_vcs_pageview_mode": "edit",
"gitlab_version": "master/",
"conf_py_path": "Documentation/"
},
}
Edit the file in GitLab WEB Ide¶
Have something like this in your jobfile.json file:
{
"Overrides_cfg": {
"general": {
"html_theme": "sphinx_rtd_theme",
"html_context": {
"display_gitlab": true,
"gitlab_host": "gitlab.com",
"gitlab_user":"-/ide/project/GITLAB_USER",
"gitlab_repo": "GITLAB_REPO",
"theme_vcs_pageview_mode": "edit",
"gitlab_version": "master/-/",
"conf_py_path": "Documentation/"
},
}
Your own logo and css with the sphinx_rtd_theme¶
To configure your own logo with the ReadTheDocs theme you need to know the
relative path from conf.py to the logo. Suppose your file structure looks
like this:
MyProject
└── Documentation
├── jobfile.json
├── Index.rst
└── _static
├── my-logo.svg
└── css
└── my-styles.css
The relative path we are looking for is a constant and reflects some of the
internals of the container. This constant, which is the relative path to go
from the conf.py folder to the documentation start is
../TheProject/Documentation. So to use my-logo.png and
my-styles.css you would write the following in jobfile.json.
To make it a bit more complete project, release and version are shown as well:
{
"Overrides_cfg": {
"general": {
"html_theme": "sphinx_rtd_theme",
"html_logo": "../TheProject/Documentation/_static/my-logo.svg",
"html_css_files": ["css/my-styles.css"],
"html_static_path": ["../TheProject/Documentation/_static"],
"project": "MyProject",
"release": "1.0.0",
"version": "1.0",
}
},
Personal use of container v2.6¶
Run the container:
cd mbw-the-mbless-world
dockrun_t3rd makehtml-no-cache -c jobfile /PROJECT/Documentation/jobfile.json
File mbw-the-mbless-world/Documentation/jobfile.json:
{
"Overrides_cfg": {
"general": {
"html_theme": "sphinx_typo3_theme",
"html_theme_options": {},
"html_logo": "../TheProject/Documentation/_static/logo/logo.png",
"html_css_files": ["css/mbwstyles.css"],
"html_favicon": "../TheProject/Documentation/_static/icons/favicon.ico",
"html_static_path": ["../TheProject/Documentation/_static"],
"html_context": {
"display_gitlab": true,
"gitlab_protocol": "http://",
"gitlab_host": "gitlab.local.mbless.de:81",
"gitlab_user":"-/ide/project/marble",
"gitlab_repo": "mbw-the-mbless-world",
"theme_vcs_pageview_mode": "edit",
"gitlab_version": "master/-/",
"conf_py_path": "Documentation/"
},
"keep_warnings": 0,
"nitpicky": false,
"nitpick_ignore": [["py:class", "type"]],
"project": "MBW - The Mbless World",
"release": "1.0.0",
"rst_epilog": "",
"rst_prolog_DISABLED": "\n.. This is 'Includes.txt'. It is included at the very top of each and\n every ReST source file in THIS documentation project (= manual).\n\n.. role:: aspect (emphasis)\n.. role:: html(code)\n.. role:: js(code)\n.. role:: php(code)\n.. role:: typoscript(code)\n.. role:: ts(typoscript)\n :class: typoscript\n\n.. highlight:: php\n.. default-role:: code\n",
"smartquotes": false,
"templates_path": ["../TheProject/Documentation/_templates"],
"todo_include_todos": true,
"version": "1.0",
"zzz": 0
}
},
"tctconfig": {
"activateLocalSphinxDebugging": 0,
"disable_include_files_check": 1,
"force_rebuild_needed": 1,
"make_html": 1,
"make_latex": 0,
"make_pdf": 0,
"make_singlehtml": 0,
"rebuild_needed": 1,
"replace_static_in_html": 0,
"reveal_exitcodes": 1,
"reveal_milestones": 1,
"talk": 1,
"try_pdf_build_from_published_latex": 1
}
}
File structure:
.
├── Documentation
│ ├── 00-Todo
│ │ ├── Explore-this
│ │ │ └── Index.rst
│ │ └── Index.rst
│ ├── 90-Targets.rst
│ ├── 91-Sitemap.rst.txt
│ ├── genindex.rst
│ ├── Includes.rst.txt
│ ├── Index.rst
│ ├── jobfile.json
│ ├── _static
│ │ ├── css
│ │ │ └── mbwstyles.css
│ │ ├── icons
│ │ │ └── favicon.ico
│ │ └── logo
│ │ ├── logo-242x242.png
│ │ └── logo.png
│ └── _templates
│ ├── breadcrumbs.html
│ └── sitemap.html
└── Documentation-GENERATED-temp
├── Cache
├── last-docker-run-command-GENERATED.sh.txt
├── Result
│ ├── exitcodes.json
│ ├── milestones.json
│ ├── project
│ │ └── 0.0.0
│ │ ├── 00-Todo
│ │ │ ├── Explore-this
│ │ │ │ └── Index.html
│ │ │ └── Index.html
│ │ ├── Index.html
│ │ ├── objects.inv
│ │ ├── search.html
│ │ ├── searchindex.js
│ │ ├── _sources
│ │ │ ├── 00-Todo
│ │ │ │ ├── Explore-this
│ │ │ │ │ └── Index.rst.txt
│ │ │ │ └── Index.rst.txt
│ │ └── _static
│ │ ├── css
│ │ │ ├── fontawesome.css
│ │ │ ├── mbwstyles.css
│ │ │ ├── theme.css
│ │ │ └── webfonts.css
│ │ ├── favicon.ico
│ │ ├── fonts
│ │ │ ├── ...
│ │ │ └── ...
│ │ ├── graphviz.css
│ │ ├── icons
│ │ │ └── favicon.ico
│ │ ├── img
│ │ │ └── typo3-logo.svg
│ │ ├── js
│ │ │ ├── autocomplete.min.js
│ │ │ └── ...
│ │ ├── language_data.js
│ │ ├── logo
│ │ │ ├── logo-242x242.png
│ │ │ └── logo.png
│ │ ├── logo.png
│ │ ├── pygments.css
│ │ └── ...
│ └── publish-params.json
└── warning-files.txt