Gestion du versionnement de la documentation avec mike

.github/workflows/build-and-release.yaml

@@ -83,8 +83,8 @@ jobs:
         if: "! contains(github.ref_name,'b') && matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
         run: |
           source .venv/bin/activate
-          coverage html -d dist/tests/
-          rm dist/tests/.gitignore
+          coverage html -d target/docs/tests/
+          rm target/docs/tests/.gitignore
 
       - name: Build package
         if: "matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
@@ -97,10 +97,19 @@ jobs:
         run: |
           source .venv/bin/activate
           pip install -e .[doc]
-          pdoc3 --html --output-dir dist/ rok4
-          cp README.md CHANGELOG.md dist/
-
-      - name: Upload packages, tests results and documentation
+          pdoc3 --html --output-dir target/docs/ rok4
+          cp docs/mkdocs.yml target/mkdocs.yml
+          cp -r docs/overrides target/
+          cp docs/unit-tests.md target/docs/unit-tests.md
+          cp docs/documentation.md target/docs/documentation.md
+          cp docs/README.hdr.md target/docs/README.md
+          cp docs/CHANGELOG.hdr.md target/docs/CHANGELOG.md
+          cp docs/CONTRIBUTING.hdr.md target/docs/CONTRIBUTING.md
+          sed "s#x.y.z#${{ github.ref_name }}#g" README.md >>target/docs/README.md
+          cat CHANGELOG.md >>target/docs/CHANGELOG.md
+          cat CONTRIBUTING.md >>target/docs/CONTRIBUTING.md
+
+      - name: Upload packages
         if: "matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
         uses: actions/upload-artifact@v3
         with:
@@ -109,6 +118,17 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+      - name: Publish documentation
+        if: "! contains(github.ref_name,'b') && matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
+        run: |
+          source .venv/bin/activate
+          pip install -r docs/requirements.txt
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          cd target/
+          mike deploy --push --update-aliases --branch gh-pages -t "Version ${{ github.ref_name }}" ${{ github.ref_name }} latest
+          mike set-default --push --branch gh-pages ${{ github.ref_name }}
+
   publish_artefacts:
     name: Add built artefacts to release and PyPI
     needs: [create_release, build_and_test]
@@ -155,56 +175,6 @@ jobs:
           password: ${{ secrets.PYPI_API_TOKEN }}
           packages_dir: to_publish/
 
-  commit_documentation:
-    name: Add documentation and unit tests results into gh-pages branch
-    needs: build_and_test
-    if: "always() && ! contains(github.ref_name,'b') && needs.create_release.outputs.job_status == 'success' && needs.build_and_test.outputs.job_status == 'success'"
-    runs-on: ubuntu-latest
-
-    steps:
-
-      - name: Checkout project on gh-pages
-        uses: actions/checkout@v4
-        with:
-          ref: 'gh-pages'
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - uses: actions/download-artifact@v3
-        with:
-          name: dist-py3
-          path: artifact/
-
-      - name: Copy version elements to final location
-        run: |
-          mkdir -p docs/versions/${{ github.ref_name }}
-          cp -r artifact/rok4 docs/versions/${{ github.ref_name }}/
-          cp -r artifact/tests docs/versions/${{ github.ref_name }}/
-
-      - name: Add pages from templates
-        run: |
-          sed "s#__version__#${{ github.ref_name }}#" templates/mkdocs.template.yml >mkdocs.yml
-
-          sed "s#__version__#${{ github.ref_name }}#" templates/unit-tests.template.md >docs/versions/${{ github.ref_name }}/unit-tests.md
-          sed "s#__version__#${{ github.ref_name }}#" templates/documentation.template.md >docs/versions/${{ github.ref_name }}/documentation.md
-
-          sed "s#__version__#${{ github.ref_name }}#" templates/index-version.template.md >docs/versions/${{ github.ref_name }}/index.md
-          cat artifact/README.md >>docs/versions/${{ github.ref_name }}/index.md
-          sed -i "s#x.y.z#${{ github.ref_name }}#g" docs/versions/${{ github.ref_name }}/index.md
-
-          cp templates/index-versions.template.md docs/versions/index.md
-          sed "s/^## \(.*\)$/## \1 \n\n[➔ Lien vers la documentation](\1\/index.md) /" artifact/CHANGELOG.md >>docs/versions/index.md
-
-          sed "s#__version__#${{ github.ref_name }}#" templates/latest.template.html >docs/versions/latest/index.html
-          rm -r artifact
-
-      - name: Publish on gh-pages branch
-        run: |
-          git config user.name github-actions
-          git config user.email github-actions@github.com
-          git add -v docs/versions/${{ github.ref_name }}/ docs/versions/latest/ docs/versions/index.md mkdocs.yml
-          git commit -m "Add documentation for version ${{ github.ref_name }}"
-          git push
-
   delete_version:
     name: Remove release and tag if error occured
     needs: build_and_test

.pre-commit-config.yaml

@@ -33,6 +33,7 @@ repos:
       - id: black
         args: ["--target-version=py38"]
 
+
   - repo: https://github.com/pycqa/isort
     rev: 5.12.0
     hooks:

docs/CHANGELOG.hdr.md

@@ -0,0 +1,4 @@
+---
+hide:
+  - navigation
+---

docs/CONTRIBUTING.hdr.md

@@ -0,0 +1,4 @@
+---
+hide:
+  - navigation
+---

docs/README.hdr.md

@@ -0,0 +1,4 @@
+---
+hide:
+  - navigation
+---

docs/documentation.md

@@ -0,0 +1,9 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# Documentation technique
+
+<iframe src="../rok4/index.html"></iframe>

docs/mkdocs.yml

@@ -0,0 +1,28 @@
+site_name: "Projet ROK4 - Librairies python"
+site_url: https://rok4.github.io/core-python
+
+nav:
+    - Accueil: README.md
+    - Documentation technique: documentation.md
+    - Rapport des tests unitaires: unit-tests.md
+    - Historique des versions: CHANGELOG.md
+    - Contribuer: CONTRIBUTING.md
+
+theme:
+    logo: https://rok4.github.io/assets/images/rok4-carre.png
+    favicon: https://rok4.github.io/assets/images/rok4-carre.png
+    name: material
+    features:
+        - navigation.tabs
+        - navigation.tabs.sticky
+    language: fr
+    custom_dir: overrides
+
+extra_css:
+    - https://rok4.github.io/assets/css/commun.css
+
+extra:
+    homepage: https://rok4.github.io
+    version:
+        provider: mike
+        default: latest

docs/overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  🚨 Vous êtes sur la documentation d'une ancienne version. 🚨
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Cliquez ici pour aller sur la dernière version.</strong>
+  </a>
+{% endblock %}

docs/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-material
+mike

docs/unit-tests.md

@@ -0,0 +1,9 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# Rapport des tests unitaires
+
+<iframe src="../tests/index.html"></iframe>

pyproject.toml

@@ -58,7 +58,7 @@ test = [
 [project.urls]
 "Homepage" = "https://rok4.github.io/core-python"
 "Bug Reports" = "https://github.com/rok4/core-python/issues"
-"Changelog" = "https://rok4.github.io/core-python/versions/"
+"Changelog" = "https://rok4.github.io/core-python/latest/CHANGELOG/"
 "Source" = "https://github.com/rok4/core-python"
 
 [build-system]