From c7084895d608052f251f247332e32f9ef7e69fdd Mon Sep 17 00:00:00 2001 From: InsanePrawn Date: Thu, 15 Dec 2022 07:07:53 +0100 Subject: [PATCH] docs: add `versions` target to produce multi-version docs ci-kbs-docs-build-full --- .gitlab-ci.yml | 46 +++++++++++++++++-- docs/.gitignore | 2 + docs/Makefile | 68 ++++++++++++++++++++++++--- docs/requirements.txt | 1 + docs/versjon/footer.html | 58 +++++++++++++++++++++++ docs/versjon/head.html | 1 + docs/versjon/header.html | 11 +++++ docs/versjon/versions.css | 96 +++++++++++++++++++++++++++++++++++++++ 8 files changed, 271 insertions(+), 12 deletions(-) create mode 100644 docs/versjon/footer.html create mode 100644 docs/versjon/head.html create mode 100644 docs/versjon/header.html create mode 100644 docs/versjon/versions.css diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 6e5d3ce..2651dc3 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -70,12 +70,17 @@ push_docker: except: .docs: - image: "${CI_REGISTRY_IMAGE}:dev" - before_script: + image: "registry.gitlab.com/kupfer/kupferbootstrap:dev" + variables: + DOCS_SPHINXARGS: '-W' + DOCS_MAKE_TARGET: "html" + DOCS_MAKE_THREADS: 6 + before_script: &docs_before_script - pip install -r requirements.txt -r docs/requirements.txt - script: - - (cd docs && SPHINXARGS='-W' make) - - mv docs/html public + script: &docs_script + - '(cd docs && make -j$DOCS_MAKE_THREADS SPHINXARGS="$DOCS_SPHINXARGS" $DOCS_MAKE_TARGET)' + after_script: + - mv "docs/$DOCS_MAKE_TARGET" public artifacts: paths: - public @@ -83,11 +88,42 @@ push_docker: build_docs: stage: build extends: .docs + except: + refs: + - main + - dev + - docs + variables: + - '$CI_COMMIT_MESSAGE =~ /ci-kbs-docs-build-full/' + - '$KBS_DOCS_FULL_BUILD == "1"' + +build_docs_all: + stage: build + extends: pages + resource_group: $CI_COMMIT_SHA + script: + - (cd docs && make SPHINXARGS="$DOCS_SPHINXARGS -D 'version=$CI_COMMIT_REF_NAME'" && mkdir -p versions && cp -r html versions/$CI_COMMIT_REF_SLUG) + - *docs_script + only: + refs: + - branches + variables: + - '$CI_COMMIT_MESSAGE =~ /ci-kbs-docs-build-full/' + - '$KBS_DOCS_FULL_BUILD == "1"' + - '$CI_COMMIT_REF_NAME == "docs"' except: - main + - dev pages: stage: deploy extends: .docs only: - main + - dev + variables: + DOCS_MAKE_TARGET: versions + resource_group: docs + before_script: + - git remote update + - *docs_before_script diff --git a/docs/.gitignore b/docs/.gitignore index 35bacdd..0cb0f6c 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,3 +2,5 @@ .doctrees html source/cli +checkouts +versions diff --git a/docs/Makefile b/docs/Makefile index 6add764..2d3a2db 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,16 +1,70 @@ -buildargs := -b dirhtml -aE source html +buildargs := -b dirhtml -aE source -.PHONY: cleanbuild clean +.PHONY: cleanbuild clean serve serve_versions versions versions_git versions_index .phony_explicit +.NOTINTERMEDIATE: +.PRECIOUS: versions/%/index.html checkouts/%/docs/html/index.html +# helper to make versions/%/index.html phony +.phony_explicit: + +BRANCHES := main dev +TAGS := $(shell git tag) +FILTERTED_TAGS := $(foreach tag,$(TAGS),$(shell if [[ -n "$$(git log --max-count=1 --oneline "$(tag)" -- .)" ]]; then echo "$(tag)"; fi)) +VERSIONS := $(BRANCHES) $(FILTERTED_TAGS) cleanbuild: - @make clean - @make html + @$(MAKE) clean + @$(MAKE) html clean: - rm -rf html source/cli .buildinfo .doctrees + rm -rf html source/cli .buildinfo .doctrees versions checkouts html: - sphinx-build $(SPHINXARGS) $(buildargs) + sphinx-build $(SPHINXARGS) $(buildargs) html serve: html - (cd html && python -m http.server 9999) + cd html && python -m http.server 9999 + +checkouts/%/docs/html/index.html: + @mkdir -p checkouts + @# use backslashed multi-line cmd because otherwise variables will be lost + @branch="$$(echo "$(@D)" | sed 's|^checkouts/||g;s|/docs/html$$||g')" && \ + ref="$$branch" && \ + if ! git log --max-count=1 --oneline "$$branch" >/dev/null 2>/dev/null ; then \ + commit="$$(git ls-remote origin refs/{tags,heads}/"$$branch" | cut -f 1)" ; \ + [[ -n "$$commit" ]] && echo "found commit $$commit for $$branch" >&2 && \ + ref="$$commit" && git branch -f "$$branch" "$$ref" ; \ + fi && \ + [[ -n "$$(git log --max-count=1 --oneline "$$ref" -- .)" ]] || \ + (echo "ERROR: branch '$$branch' seems to have no docs/ dir, checked ref '$$ref'" >&2 && exit 1) && \ + checkout="checkouts/$$branch" && \ + ver="$$(echo "$$branch" | sed 's|^v\([0-9]\)|\1|g')" && \ + set -x && \ + ([[ -e "$$checkout/.git" ]] || git clone .. "$$checkout" ) && \ + (! [[ -e "$$checkout/docs/source/conf.py" ]] || echo "version = '$$ver'" >> "$$checkout/docs/source/conf.py") && \ + $(MAKE) -C "$$checkout/docs" SPHINXARGS="-D version=$$ver" + +versions/%/index.html: checkouts/%/docs/html/index.html .phony_explicit + @mkdir -p versions + @# use backslashed multi-line cmd because otherwise variables will be lost + @branch="$$(basename "$(@D)")" && \ + checkout="checkouts/$$branch" && \ + echo "working on version '$$branch'" && \ + set -x && \ + cp -rf "$$checkout/docs/html/." "versions/$$branch/" + +versions/versions.css: versjon/versions.css + @mkdir -p versions + cp versjon/versions.css versions/ + +versions_git: + @$(MAKE) $(patsubst %, versions/%/index.html, $(VERSIONS)) + +versions/index.html: + rm -rf versions/stable + @cd versions && set -x && versjon --stable-version main --user_templates ../versjon + +versions: versions_git versions/versions.css + @$(MAKE) versions/index.html + +serve_versions: versions + cd versions && python -m http.server 9888 diff --git a/docs/requirements.txt b/docs/requirements.txt index f9a29ab..1fe6156 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,3 +2,4 @@ sphinx-click myst-parser # furo sphinx theme furo +versjon<=2.3.0 diff --git a/docs/versjon/footer.html b/docs/versjon/footer.html new file mode 100644 index 0000000..f0de772 --- /dev/null +++ b/docs/versjon/footer.html @@ -0,0 +1,58 @@ +{# FORMAT_VERSION #} + +{% macro format_version(version) %} +{% if page in version.html_files %} +{% set version_path = page_root + docs_path[version.name] + "/" + page %} +{% else %} +{% set version_path = page_root + docs_path[version.name] %} +{% endif %} +{% if current == version.name %} + +
{{ version.name }}
+ +{% else %} +
{{ version.name }}
+{% endif %} +{% endmacro %} + +
+ +
+
+
+
+
Branches
+ {% for version in other %} + {{ format_version(version) | indent(16) }} + {% endfor %} +
+
Versions
+ {% for version in semver %} + {{ format_version(version) | indent(16) }} + {% endfor %} +
+
+
+
+ diff --git a/docs/versjon/head.html b/docs/versjon/head.html new file mode 100644 index 0000000..c5e7ea2 --- /dev/null +++ b/docs/versjon/head.html @@ -0,0 +1 @@ + diff --git a/docs/versjon/header.html b/docs/versjon/header.html new file mode 100644 index 0000000..2894612 --- /dev/null +++ b/docs/versjon/header.html @@ -0,0 +1,11 @@ +{% if stable and (stable.name|default("")) != current %} +{% if page in stable.html_files %} +{% set stable_path = page_root + docs_path[stable.name] + "/" + page %} +{% else %} +{% set stable_path = page_root + docs_path[stable.name] %} +{% endif %} +

+ Warning: These docs are for version {{current}}. The docs for the latest stable version are at + {{ stable.name }} . +

+{% endif %} diff --git a/docs/versjon/versions.css b/docs/versjon/versions.css new file mode 100644 index 0000000..cc8885d --- /dev/null +++ b/docs/versjon/versions.css @@ -0,0 +1,96 @@ +.versjon { + cursor: pointer; + padding: 10px; + width: 100%; + border: none; + text-align: left; + outline: none; + font-size: 15px; + background: var(--color-code-background); + color: var(--color-code-foreground); + transition: background-color 0.1s linear; +} + +.versjon:hover { + background-color: var(--color-highlighted-background); +} + +.versjon:after { + content: '\002B'; + font-weight: bold; + float: right; + margin-left: 5px; +} + +.versjon:active:after { + content: "\2212"; +} + +.versjon-content { + max-height: 0; + overflow: hidden; + transition: max-height 0.2s ease-out; +} + +.versjon-content-inner { + padding: 10px 18px +} + +#versjon-overlay { + position: fixed; + bottom: 0px; + right: 0px; + width: 250px; + background: var(--color-code-background); +} + +p.versjon-old-warning { + margin: 10px 0; + padding: 5px 10px; + border-radius: 4px; + + letter-spacing: 1px; + color: #fff; + text-shadow: 0 0 2px #000; + text-align: center; + + background: #d40 repeating-linear-gradient(135deg, + transparent, + transparent 56px, + rgba(255, 255, 255, 0.2) 56px, + rgba(255, 255, 255, 0.2) 112px); +} + +p.versjon-old-warning a { + color: #fff; + border-color: #fff; +} + +p.versjon-dev-warning { + margin: 10px 0; + padding: 5px 10px; + border-radius: 4px; + + letter-spacing: 1px; + color: #fff; + text-shadow: 0 0 2px #000; + text-align: center; + + background: #E67300 repeating-linear-gradient(135deg, + transparent, + transparent 56px, + rgba(255, 255, 255, 0.2) 56px, + rgba(255, 255, 255, 0.2) 112px); +} + +p.versjon-dev-warning a { + color: #fff; + border-color: #fff; +} + +#branch-icon { + width: 1em; + height: 1em; + background-size: contain; + background-repeat: no-repeat; +}