Include documentation for multiple project versions in a single GitLab page
Project description
gitlab-versioned-pages
Include documentation for multiple project versions in a single GitLab page.
Overview
This package can be used inside a pages
job in your .gitlab-ci.yml
pipeline in order to combine documentation for all tagged versions of the package. See the .gitlab-ci.yml
of this package for an example.
This package also generates a versions.json
, which can be used together with e.g. the Sphinx msmb_theme
in order to include a version selector on the documentation page for each version
Usage
Add the following stage in your .gitlab-ci.yml
file to collect documentations for all tagged versions and include them in a single page. The GITLAB_TOKEN
is a private token that can be created manually inside the GitLab settings page.
pages:
stage: custom
before_script:
- pip install gitlab_versioned_pages
script:
- mkdir -p ./public
- python -m gitlab_versioned_pages
--project-id ${CI_PROJECT_ID}
--job-name docs
--private-token ${GITLAB_TOKEN}
--output-dir ./public
--url "https://${CI_PROJECT_NAMESPACE}.gitlab.io/${CI_PROJECT_NAME}"
artifacts:
paths:
- public
only:
variables:
- $UPDATE_PAGES
Implementation details
This file creates a ./public
folder containing documentation created for multiple versions (tags) of this repository.
When the repository is public, our job is easy: we simply download the artifact.zip
file from a publicly-accessible URL (see: downloading the latest artifacts). However, when the repository is private, using the above-mentioned URL does not work (see: gitlab-org/gitlab-ce#22957). In that case, we resort to using the GitLab API instead.
If gitlab-org/gitlab-ce#22957 is ever fixed, we would be able to specify
--header "Private-Token: XXXXX"
or attach &private_token=XXXXX
to the query string,
and keep using the original URL:
curl --header "Private-Token: XXXXX" \
"https://gitlab.com/user/repo/-/jobs/artifacts/ref/download?job=job_name"
Good resource: https://docs.gitlab.com/ee/api/jobs.html#download-the-artifacts-archive.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for gitlab-versioned-pages-0.1.6.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8dec708938ac772250d8ccd04dc3ebaad8288ef70a6b9ee9e1ac6e1fc2fa3c71 |
|
MD5 | d659e2c050c3db237122ec170dbc7220 |
|
BLAKE2b-256 | ef59a4f92630c8026f3a85c7fc3e629f499994f77ca04c177d363854b829c69d |
Hashes for gitlab_versioned_pages-0.1.6-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7e6b9f3db79af6f61602970ea40b6e4839aa9cb3e326c05214ae64c65ab8dbc3 |
|
MD5 | a97581fa6003ededb7a39565a22a6bb1 |
|
BLAKE2b-256 | f0608b79084ddd4d1f1a11a313bc1dfa9f451179091a9b1e85446dfa9a4aaae1 |