Gestion du versionnement de la documentation avec mike

.bumpversion.cfg

@@ -0,0 +1,9 @@
+[bumpversion]
+parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(b(?P<beta>\d+))?
+serialize =
+	{major}.{minor}.{patch}b{beta}
+	{major}.{minor}.{patch}
+
+[bumpversion:file:pyproject.toml]
+
+[bumpversion:file:src/rok4_tools/__init__.py]

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

@@ -1,9 +1,10 @@
-name: Build and publish artefacts and documentation
+name: Test, build and publish artefacts and documentation
 
 on:
   push:
     tags:
-      - '**'
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+b[0-9]+'
 
 jobs:
 
@@ -15,7 +16,7 @@ jobs:
       job_status: ${{ job.status }}
     steps:
       - name: Checkout project
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Create Release
         id: create_release
@@ -26,11 +27,11 @@ jobs:
           name: Release ${{ github.ref_name }}
           generateReleaseNotes: true
           draft: false
-          prerelease: false
+          prerelease: ${{ contains(github.ref_name ,'b') }}
 
-  build:
+  build_and_test:
 
-    name: Build artefacts
+    name: Test and build artefacts
     needs: create_release
     outputs:
       job_status: ${{ job.status }}
@@ -48,7 +49,7 @@ jobs:
 
     steps:
       - name: Checkout project
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup python
         uses: actions/setup-python@v4
@@ -67,27 +68,50 @@ jobs:
           python3 -m venv .venv
           source .venv/bin/activate
           python3 -m pip install --upgrade build bump2version
-          bump2version --current-version 0.0.0 --new-version ${{ github.ref_name }} patch pyproject.toml src/rok4_tools/__init__.py
+          bump2version --current-version 0.0.0 --new-version ${{ github.ref_name }} patch
           pip install -e .
           echo "/usr/lib/python3/dist-packages/" >.venv/lib/python${{ matrix.python-version }}/site-packages/system.pth
 
+      - name: Run unit tests
+        run: |
+          source .venv/bin/activate
+          pip install -e .[test]
+          coverage run -m pytest
+          coverage report -m
+
+      - name: Build unit tests report
+        if: "! contains(github.ref_name,'b') && matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
+        run: |
+          source .venv/bin/activate
+          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'"
         run: |
           source .venv/bin/activate
           python3 -m build
 
       - name: Build documentation
-        if: "matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
+        if: "! contains(github.ref_name,'b') && matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
         run: |
           source .venv/bin/activate
           pip install -e .[doc]
-          pdoc3 --html --output-dir dist/ rok4_tools
-          cp README.md CHANGELOG.md dist/
-          cp -r docs/images dist/
-
-
-      - name: Upload packages and documentation
+          pdoc3 --html --output-dir target/docs/ rok4_tools
+          cp docs/mkdocs.yml target/mkdocs.yml
+          cp -r docs/overrides target/
+          cp -r docs/images target/docs/
+          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
+          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: Upload packages
         if: "matrix.os == 'ubuntu-20.04' && matrix.python-version == '3.8'"
         uses: actions/upload-artifact@v3
         with:
@@ -96,10 +120,21 @@ 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]
-    if: "always()&&(needs.create_release.outputs.job_status=='success')&&(needs.build.outputs.job_status=='success')"
+    needs: [create_release, 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:
@@ -121,7 +156,7 @@ jobs:
           asset_content_type: application/zip
 
       - name: Add tarball package to release
-        id: upload-release-targz 
+        id: upload-release-targz
         uses: actions/upload-release-asset@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -142,67 +177,17 @@ jobs:
           password: ${{ secrets.PYPI_API_TOKEN }}
           packages_dir: to_publish/
 
-  commit_documentation:
-    name: Add documentation into gh-pages branch
-    needs: build
-    if: "always()&&(needs.create_release.outputs.job_status=='success')&&(needs.build.outputs.job_status=='success')" 
-    runs-on: ubuntu-latest
-
-    steps:
-
-      - 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: Copy version elements to final location
-        run: |
-          mkdir -p docs/versions/${{ github.ref_name }}/docs
-          cp -r artifact/rok4_tools 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
-        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
-    if: "always()&&(needs.create_release.outputs.job_status=='success')&&(needs.build.outputs.job_status!='success')" 
+    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:
       - name: Remove release and tag
-        uses: dev-drprasad/delete-tag-and-release@v0.2.0
+        uses: dev-drprasad/delete-tag-and-release@v1.0.1
         with:
           tag_name: ${{ github.ref_name }}
           delete_release: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-

.pre-commit-config.yaml

@@ -21,8 +21,14 @@ repos:
       - id: trailing-whitespace
         args: [--markdown-linebreak-ext=md]
 
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.0.291"
+    hooks:
+      - id: ruff
+        args: ["--fix-only", "--target-version=py38"]
+
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.9.1
     hooks:
       - id: black
         args: ["--target-version=py38"]
@@ -35,8 +41,14 @@ repos:
         args: ["--profile", "black", "--filter-files"]
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.1
+    rev: v3.13.0
     hooks:
       - id: pyupgrade
         args:
           - "--py38-plus"
+
+ci:
+  autofix_commit_msg: "[pre-commit.ci] Corrections automatiques appliquées par les git hooks."
+  autofix_prs: true
+  autoupdate_commit_msg: "[pre-commit.ci] Mise à jour des git hooks."
+  autoupdate_schedule: quarterly

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

docs/mkdocs.yml

@@ -0,0 +1,28 @@
+site_name: "Projet ROK4 - Outils python"
+site_url: https://rok4.github.io/pytools
+
+nav:
+    - Accueil: README.md
+    - Documentation développeur: 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>