doc: use mike to keep old released doc

2024-11-24 02:49:07 +01:00 · 2023-10-08 10:22:25 +02:00 · 2023-10-08 10:22:25 +02:00 · d9254a3be7
commit d9254a3be7
parent 1639001a3c
5 changed files with 106 additions and 18 deletions
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@ -3,11 +3,15 @@ stages:
  - build
  - publish

+variables:
+  DOC_BRANCH: doc
+  DOC_REMOTE: https://gitlab-ci-token:${ACCESS_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
 tests:bullseye:
  image:
    name: brenard/ldapsaisie:bullseye
    entrypoint: [""]
-
  stage: tests
  rules:
    - changes:
@ -33,7 +37,6 @@ tests:buster:
  image:
    name: brenard/ldapsaisie:buster
    entrypoint: [""]
-
  stage: tests
  rules:
    - changes:
@ -89,6 +92,11 @@ tests:jessie:
 build:debian-sid:
  image: brenard/debian-python-deb:debian11
  stage: build
+  cache:
+    paths:
+      - .cache/pip
+  only:
+    - master
  script:
    - ./build-deb.sh --install-build-deps --sid
  artifacts:
@ -98,23 +106,42 @@ build:debian-sid:
 build:snapshot:
  stage: build
  image: alpine
+  only:
+    - master
  script:
    - tar -czf ldapsaisie-snapshot.tar.gz --exclude=ldapsaisie-snapshot.tar.gz ./
  artifacts:
    paths:
      - ldapsaisie-snapshot.tar.gz

-build:doc:
+build:doc:html:
  stage: build
  image: python:alpine
+  cache:
+    paths:
+      - .cache/pip
+      - doc/venv
+  only:
+    - master
  before_script:
-    - apk add make
-  script:
+    - apk add make git
+    - git config user.name $GITLAB_USER_NAME
+    - git config user.email $GITLAB_USER_EMAIL
+    - VERSION=`git describe --tags`
    - cd doc
-    - make public_html LdapSaisie.html
+    - git fetch origin $DOC_BRANCH
+    - git rev-parse --verify $DOC_BRANCH && git branch -D $DOC_BRANCH || echo "No existing local git $DOC_BRANCH branch"
+    - git checkout -b $DOC_BRANCH origin/$DOC_BRANCH
+    - git checkout $CI_COMMIT_SHA
+    - make clean && make venv
+  script:
+    - make LdapSaisie.html
+    - test -n "$CI_COMMIT_TAG" && DOC_TAG=stable || DOC_TAG=dev
+    - source venv/bin/activate  # We must have to activate the venv to use mike (direct call not supported)
+    - mike deploy --rebase --prefix doc/dist --remote $DOC_REMOTE --push --branch $DOC_BRANCH --update-aliases $VERSION $DOC_TAG
+    - mike set-default --rebase --prefix doc/dist --remote $DOC_REMOTE --push --branch $DOC_BRANCH $DOC_TAG
  artifacts:
    paths:
-      - doc/public_html/
      - doc/LdapSaisie.html

 build:doc:pdf:
@ -122,10 +149,13 @@ build:doc:pdf:
  image:
    name: pink33n/html-to-pdf
    entrypoint: ["/bin/sh", "-c"]
+  only:
+    - master
  needs:
-    - build:doc
+    - build:doc:html
  script:
-    - /usr/local/bin/entrypoint --url file://$(pwd)/doc/LdapSaisie.html --pdf doc/LdapSaisie.pdf
+    - rm -f doc/LdapSaisie.pdf
+    - /usr/local/bin/entrypoint --url file://$(pwd)/doc/LdapSaisie.html --pdf doc/LdapSaisie.pdf || test -f doc/LdapSaisie.pdf
  artifacts:
    paths:
      - doc/LdapSaisie.pdf
@ -135,8 +165,10 @@ build:doc:epub:
  image:
    name: pandoc/core
    entrypoint: ["/bin/sh", "-c"]
+  only:
+    - master
  needs:
-    - build:doc
+    - build:doc:html
  before_script:
    - apk add make
  script:
@ -147,14 +179,58 @@ build:doc:epub:
    paths:
      - doc/LdapSaisie.epub

-publish:
+build:doc:append_additional_versions:
+  stage: build
+  image: python:alpine
+  only:
+    - master
+  needs:
+    - build:doc:html
+    - build:doc:pdf
+    - build:doc:epub
+  before_script:
+    - apk add git
+    - git config user.name $GITLAB_USER_NAME
+    - git config user.email $GITLAB_USER_EMAIL
+    - VERSION=`git describe --tags`
+    - cd doc
+    - git fetch origin $DOC_BRANCH
+    - git rev-parse --verify $DOC_BRANCH && git branch -D $DOC_BRANCH || echo "No existing local git $DOC_BRANCH branch"
+    - git checkout -b $DOC_BRANCH origin/$DOC_BRANCH
+    - git pull origin $DOC_BRANCH
+  script:
+    - cp LdapSaisie.html LdapSaisie.pdf LdapSaisie.epub dist/$VERSION/
+    - git add dist/$VERSION/
+    - git commit --amend --no-edit
+    - git push --force $DOC_REMOTE $DOC_BRANCH
+
+publish:doc:
  stage: publish
  image: alpine:latest
+  only:
+    - master
  needs:
-    - 'build:doc'
-    - 'build:doc:pdf'
-    - 'build:doc:epub'
-    - 'build:snapshot'
+    - build:doc:append_additional_versions
+  before_script:
+    - apk update && apk add git openssh-client rsync
+    - eval $(ssh-agent -s)
+    - echo "$SSH_PRIVATE_KEY" | base64 -d | ssh-add -
+    - mkdir ~/.ssh
+    - echo "$SSH_HOST_KEY" | base64 -d > ~/.ssh/known_hosts
+    - git fetch origin $DOC_BRANCH
+    - git rev-parse --verify $DOC_BRANCH && git branch -D $DOC_BRANCH || echo "No existing local git $DOC_BRANCH branch"
+    - git checkout -b $DOC_BRANCH origin/$DOC_BRANCH
+    - git pull origin $DOC_BRANCH
+  script:
+    - rsync -atv --exclude '.git*' --delete --progress ./doc/dist/ $SSH_USER@$SSH_HOST:doc/
+
+publish:snapshot:
+  stage: publish
+  image: alpine:latest
+  only:
+    - master
+  needs:
+    - build:snapshot
  before_script:
    - apk update && apk add openssh-client rsync
    - eval $(ssh-agent -s)
@ -162,15 +238,15 @@ publish:
    - mkdir ~/.ssh
    - echo "$SSH_HOST_KEY" | base64 -d > ~/.ssh/known_hosts
  script:
-    - rsync -atv --exclude '.git*' --delete --progress ./doc/public_html/ $SSH_USER@$SSH_HOST:doc/
-    - rsync -atv ./doc/LdapSaisie.html ./doc/LdapSaisie.pdf ./doc/LdapSaisie.epub $SSH_USER@$SSH_HOST:doc/
    - rsync -atv ldapsaisie-snapshot.tar.gz $SSH_USER@$SSH_HOST:download/ldapsaisie-snapshot.tar.gz

 publish:debian-sid:
  stage: publish
  image: debian:stable-slim
+  only:
+    - master
  needs:
-    - 'build:debian-sid'
+    - build:debian-sid
  before_script:
    - apt-get update
    - apt-get install -y --no-install-recommends rsync openssh-client dupload
--- a/doc/.gitignore
+++ b/doc/.gitignore
@ -3,3 +3,4 @@ LdapSaisie.html
 LdapSaisie.pdf
 LdapSaisie.epub
 venv
+dist
--- a/doc/Makefile
+++ b/doc/Makefile
@ -26,6 +26,7 @@ LdapSaisie.epub: LdapSaisie.html

 venv:
 	python3 -m venv venv
+	venv/bin/python -m pip install --upgrade pip setuptools
 	venv/bin/python -m pip install -r requirements.txt

 clean:
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@ -1,9 +1,11 @@
 site_name: LdapSaisie
 site_description: Documentation
 site_author: Benjamin Renard <brenard@easter-eggs.com / brenard@zionetrix.net>
+site_url: https://ldapsaisie.org/doc/
 copyright: Easter-eggs
 docs_dir: 'src'
 site_dir: 'public_html'
+repo_name: ee/ldapsaisie
 repo_url: https://gitlab.easter-eggs.com/ee/ldapsaisie

 theme:
@ -18,10 +20,17 @@ theme:

 extra:
  homepage: https://ldapsaisie.org
+  version:
+    provider: mike

 plugins:
  - search:
      lang: fr                                      # Set language for search
+  - mike:
+      canonical_version: null
+      version_selector: true
+      css_dir: css
+      javascript_dir: js
  - print-site:
      add_to_navigation: true
      print_page_title: 'Documentation'
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@ -6,3 +6,4 @@ mkdocs-print-site-plugin==1.3.0
 html5lib
 requests
 htmlark
+mike