mirror of
https://gitlab.com/kupfer/kupferbootstrap.git
synced 2025-02-23 05:35:44 -05:00
docs: add versions target to produce multi-version docs
ci-kbs-docs-build-full
This commit is contained in:
InsanePrawn
parent
dc59378243
commit
c7084895d6
8 changed files with 271 additions and 12 deletions
|
|
@ -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
|
||||
|
|
@ -84,10 +89,41 @@ 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
|
||||
|
|
|
|||
2
docs/.gitignore
vendored
2
docs/.gitignore
vendored
|
|
@ -2,3 +2,5 @@
|
|||
.doctrees
|
||||
html
|
||||
source/cli
|
||||
checkouts
|
||||
versions
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -2,3 +2,4 @@ sphinx-click
|
|||
myst-parser
|
||||
# furo sphinx theme
|
||||
furo
|
||||
versjon<=2.3.0
|
||||
|
|
|
|||
58
docs/versjon/footer.html
Normal file
58
docs/versjon/footer.html
Normal file
|
|
@ -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 %}
|
||||
<strong>
|
||||
<dd><a href="{{ version_path }}">{{ version.name }}</a></dd>
|
||||
</strong>
|
||||
{% else %}
|
||||
<dd><a href="{{ version_path }}">{{ version.name }}</a></dd>
|
||||
{% endif %}
|
||||
{% endmacro %}
|
||||
|
||||
<div id="versjon-overlay">
|
||||
<button type="button" class="versjon">
|
||||
<svg xmlns="http://www.w3.org/2000/svg" id="branch-icon" class="ionicon" viewBox="0 0 512 512">
|
||||
<!-- Taken from Ionic, MIT licensed. Copyright (c) 2015-present Ionic (http://ionic.io/) -->
|
||||
<title>Git Branch</title><circle cx="160" cy="96" r="48" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="32"/><circle cx="160" cy="416" r="48" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="32"/><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="32" d="M160 368V144"/><circle cx="352" cy="160" r="48" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="32"/><path d="M352 208c0 128-192 48-192 160" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="32"/>
|
||||
</svg>
|
||||
Version: {{current}}
|
||||
</button>
|
||||
<div class="versjon-content">
|
||||
<div class="versjon-content-inner">
|
||||
<dl>
|
||||
<dl>
|
||||
<dt>Branches</dt>
|
||||
{% for version in other %}
|
||||
{{ format_version(version) | indent(16) }}
|
||||
{% endfor %}
|
||||
</dl>
|
||||
<dt>Versions</dt>
|
||||
{% for version in semver %}
|
||||
{{ format_version(version) | indent(16) }}
|
||||
{% endfor %}
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<script>
|
||||
var coll = document.getElementsByClassName("versjon");
|
||||
var i;
|
||||
|
||||
for (i = 0; i < coll.length; i++) {
|
||||
coll[i].addEventListener("click", function () {
|
||||
this.classList.toggle("active");
|
||||
var content = this.nextElementSibling;
|
||||
if (content.style.maxHeight) {
|
||||
content.style.maxHeight = null;
|
||||
} else {
|
||||
content.style.maxHeight = content.scrollHeight + "px";
|
||||
}
|
||||
});
|
||||
}
|
||||
</script>
|
||||
1
docs/versjon/head.html
Normal file
1
docs/versjon/head.html
Normal file
|
|
@ -0,0 +1 @@
|
|||
<link href="{{ page_root }}versions.css" rel="stylesheet" type="text/css">
|
||||
11
docs/versjon/header.html
Normal file
11
docs/versjon/header.html
Normal file
|
|
@ -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 %}
|
||||
<p class="versjon-{% if is_semver %}old{% else %}dev{% endif %}-warning">
|
||||
<strong>Warning:</strong> These docs are for version <b>{{current}}</b>. The docs for the latest stable version are at
|
||||
<b> <a href="{{ stable_path }}">{{ stable.name }}</a> </b>.
|
||||
</p>
|
||||
{% endif %}
|
||||
96
docs/versjon/versions.css
Normal file
96
docs/versjon/versions.css
Normal file
|
|
@ -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;
|
||||
}
|
||||
Loading…
Add table
Reference in a new issue