Gestion du versionnement de la documentation avec mike

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

@@ -79,66 +79,37 @@ jobs:
           cd build
           make doc
           cd ..
-          cp -r README.md CHANGELOG.md docs/images dist/
 
-      - name: Upload documentation
-        if: "matrix.os == 'ubuntu-20.04'"
-        uses: actions/upload-artifact@v3
+          cp docs/mkdocs.yml target/mkdocs.yml
+          cp -r docs/overrides target/
+          cp -r docs/images target/docs/
+          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
+          sed -i "s#](./docs/images/#](./images/#g" target/docs/README.md
+          cat CHANGELOG.md >>target/docs/CHANGELOG.md
+          cat CONTRIBUTING.md >>target/docs/CONTRIBUTING.md
+
+
+      - name: Setup python
+        uses: actions/setup-python@v4
         with:
-          name: dist-py3
-          path: dist/
-          if-no-files-found: error
-          retention-days: 1
-
-  commit_documentation:
-    name: Add documentation into gh-pages branch
-    needs: build_and_test
-    if: "always()&&(needs.create_release.outputs.job_status=='success')&&(needs.build_and_test.outputs.job_status=='success')" 
-    runs-on: ubuntu-latest
-
-    steps:
+          python-version: "3.10"
+          cache: 'pip'
 
-      - name: Checkout project on gh-pages
-        uses: actions/checkout@v3
-        with:
-          ref: 'gh-pages'
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - uses: actions/download-artifact@v3
-        with:
-          name: dist-py3
-          path: artifact/
+      - name: Install Mkdocs
+        run: pip install -r docs/requirements.txt
 
-      - name: Copy version elements to final location
-        run: |
-          mkdir -p docs/versions/${{ github.ref_name }}/docs
-          cp -r artifact/html docs/versions/${{ github.ref_name }}/
-          cp -r artifact/images docs/versions/${{ github.ref_name }}/docs/
-
-
-      - 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/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
+      - name: Publish documentation
+        if: "matrix.os == 'ubuntu-20.04'"
         run: |
           git config user.name github-actions
           git config user.email [email protected]
-          git add -v docs/versions/${{ github.ref_name }}/ docs/versions/latest/ docs/index.md docs/versions/index.md
-          git commit -m "Add documentation for version ${{ github.ref_name }}"
-          git push
+          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 }}
 
   delete_version:
     name: Remove release and tag if error occured

.gitignore

@@ -1,2 +1,3 @@
 build
-dist
+dist
+target

CMakeLists.txt

@@ -84,7 +84,7 @@ endforeach()
 if(DOC_ENABLED)
 
     set(DOXYGEN_DOXYFILE_ENCODING UTF-8)
-    set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/dist)
+    set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/target/docs)
     set(DOXYGEN_OUTPUT_LANGUAGE french)
     set(DOXYGEN_INPUT_ENCODING UTF-8)
     set(DOXYGEN_IMAGE_PATH docs/images)

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="../html/index.html"></iframe>

docs/mkdocs.yml

@@ -0,0 +1,27 @@
+site_name: "Projet ROK4 - Outils de génération de dalles raster et vecteur"
+site_url: https://rok4.github.io/generation
+
+nav:
+    - Accueil: README.md
+    - Documentation technique: documentation.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