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"
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.5.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7a98af099da64c79901ee2ffbbc9b158897c5b30f43fb35ee009953ffd49b156 |
|
MD5 | 87cc7f678deac6988d1f94147d544b6b |
|
BLAKE2b-256 | b6b6ede5513af98998ea3210957daa4068a9e4660d5d54ff20ca1e873d3bfdd1 |
Hashes for gitlab_versioned_pages-0.1.5-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7632a857bfa69b72e43a14b630a184d9a650107c56d37c13b4d95cc05a9c04e4 |
|
MD5 | 4ffe49a6084feb8ae14ab88970b7b7da |
|
BLAKE2b-256 | b5a25e9a4f8a3fcadd8d21b054c9f1a51f922ceedc140c59984ca2da6e61de2c |