From f95d1de02daf114b577724229f71e9f4a59202e7 Mon Sep 17 00:00:00 2001
From: Julian Rother <julian@jrother.eu>
Date: Tue, 23 Nov 2021 16:54:43 +0100
Subject: [PATCH] Deploy docs to Gitlab Pages with sphinx-multiversion
---
.gitlab-ci.yml | 17 +++++++++++++++--
docs/_templates/versions.html | 27 +++++++++++++++++++++++++++
docs/conf.py | 10 ++++++++--
3 files changed, 50 insertions(+), 4 deletions(-)
create mode 100644 docs/_templates/versions.html
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 68af49f..ee06f4b 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -42,8 +42,8 @@ build:apt:
build:docs:
extends: .build
script:
- - pip3 install Sphinx sphinx-rtd-theme
- - cd docs && make html
+ - pip3 install Sphinx sphinx-rtd-theme sphinx-multiversion
+ - sphinx-build docs docs/_build/html
artifacts:
paths:
- docs/_build/html/index.html
@@ -176,3 +176,16 @@ publish:apt:
- 'curl --user "${APTLY_API_USER}:${APTLY_API_PW}" -X PUT -H "Content-Type: application/json" --data "{ }" "${APT_API_URL}/api/publish/uffd/bullseye"'
dependencies:
- build:apt
+
+pages:
+ stage: deploy
+ script:
+ - pip3 install Sphinx sphinx-rtd-theme sphinx-multiversion
+ - sphinx-multiversion docs public
+ - printf '/ /master 302\n/python-ldapserver /python-ldapserver/master 302\n' > public/_redirects
+ - du -sch public
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: '$CI_COMMIT_TAG =~ /v[0-9]+[.][0-9]+[.][0-9]+.*/ || $CI_COMMIT_BRANCH == "master"'
diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html
new file mode 100644
index 0000000..31a1257
--- /dev/null
+++ b/docs/_templates/versions.html
@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+ <span class="rst-current-version" data-toggle="rst-current-version">
+ <span class="fa fa-book"> Other Versions</span>
+ v: {{ current_version.name }}
+ <span class="fa fa-caret-down"></span>
+ </span>
+ <div class="rst-other-versions">
+ {%- if versions.tags %}
+ <dl>
+ <dt>Tags</dt>
+ {%- for item in versions.tags %}
+ <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+ {%- endfor %}
+ </dl>
+ {%- endif %}
+ {%- if versions.branches %}
+ <dl>
+ <dt>Branches</dt>
+ {%- for item in versions.branches %}
+ <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+ {%- endfor %}
+ </dl>
+ {%- endif %}
+ </div>
+</div>
+{%- endif %}
diff --git a/docs/conf.py b/docs/conf.py
index 1463acf..74e1d91 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,4 +1,4 @@
-# Configuration file for the Sphinx documentation builder.
+#Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
@@ -28,7 +28,7 @@ author = 'Julian Rother'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary',
- 'sphinx.ext.intersphinx', 'sphinx.ext.coverage']
+ 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx_multiversion']
autodoc_inherit_docstrings = False
autodoc_member_order = 'bysource'
@@ -37,6 +37,12 @@ intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
}
+smv_tag_whitelist = r'^v[0-9]+\.[0-9]+\.[0-9]+$'
+smv_branch_whitelist = r'^master$'
+smv_remote_whitelist = r'^origin$'
+#smv_released_pattern = r'^tags/v[0-9]+\.[0-9]+\.[0-9]+$'
+smv_prefer_remote_refs = False
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
--
GitLab