From 1422cc5fec97e2d00d132d84fd333d11023f15a2 Mon Sep 17 00:00:00 2001 From: Theo Satabin Date: Mon, 29 Jan 2024 13:07:59 +0100 Subject: [PATCH 1/4] Gestion des versions de documentation avec mike --- .github/workflows/build-and-release.yaml | 83 ++++++++---------------- .github/workflows/build-docs.yaml | 67 ------------------- docs/CHANGELOG.hdr.md | 4 ++ docs/CONTRIBUTING.hdr.md | 4 ++ docs/README.hdr.md | 4 ++ docs/assets/style.css | 33 ++++++++++ docs/documentation.md | 9 +++ docs/mkdocs.yml | 28 ++++++++ docs/overrides/main.html | 8 +++ docs/requirements.txt | 3 + docs/unit-tests.md | 9 +++ 11 files changed, 129 insertions(+), 123 deletions(-) delete mode 100644 .github/workflows/build-docs.yaml create mode 100644 docs/CHANGELOG.hdr.md create mode 100644 docs/CONTRIBUTING.hdr.md create mode 100644 docs/README.hdr.md create mode 100644 docs/assets/style.css create mode 100644 docs/documentation.md create mode 100644 docs/mkdocs.yml create mode 100644 docs/overrides/main.html create mode 100644 docs/requirements.txt create mode 100644 docs/unit-tests.md diff --git a/.github/workflows/build-and-release.yaml b/.github/workflows/build-and-release.yaml index b464b69..16146f0 100644 --- a/.github/workflows/build-and-release.yaml +++ b/.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,20 @@ 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 -r docs/assets 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 + 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 +119,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 +176,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 diff --git a/.github/workflows/build-docs.yaml b/.github/workflows/build-docs.yaml deleted file mode 100644 index 53fd700..0000000 --- a/.github/workflows/build-docs.yaml +++ /dev/null @@ -1,67 +0,0 @@ -name: Build doc site with mkdocs and deploy - -on: - workflow_dispatch: - -jobs: - - build: - - name: Build doc site with mkdocs - - runs-on: ubuntu-latest - - steps: - - name: Checkout project - uses: actions/checkout@v4 - with: - ref: 'gh-pages' - token: ${{ secrets.GITHUB_TOKEN }} - - - name: Setup python - uses: actions/setup-python@v4 - with: - python-version: "3.10" - cache: 'pip' - - - name: Install Mkdocs - run: pip install -r requirements.txt - - - name: Run mkdocs and archive - run : | - mkdocs build - tar \ - --dereference --hard-dereference \ - --directory "site" \ - -cvf "${{ runner.temp }}/site.tar" \ - --exclude=.git \ - --exclude=.github \ - . - - - name: Upload pages - uses: actions/upload-artifact@main - with: - name: github-pages - path: ${{ runner.temp }}/site.tar - retention-days: 1 - - deploy: - - name: Deploy site to github pages - - needs: build - - permissions: - pages: write # to deploy to Pages - id-token: write # to verify the deployment originates from an appropriate source - - # Deploy to the github-pages environment - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - - runs-on: ubuntu-latest - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v2 diff --git a/docs/CHANGELOG.hdr.md b/docs/CHANGELOG.hdr.md new file mode 100644 index 0000000..e0257d2 --- /dev/null +++ b/docs/CHANGELOG.hdr.md @@ -0,0 +1,4 @@ +--- +hide: + - navigation +--- diff --git a/docs/CONTRIBUTING.hdr.md b/docs/CONTRIBUTING.hdr.md new file mode 100644 index 0000000..e0257d2 --- /dev/null +++ b/docs/CONTRIBUTING.hdr.md @@ -0,0 +1,4 @@ +--- +hide: + - navigation +--- diff --git a/docs/README.hdr.md b/docs/README.hdr.md new file mode 100644 index 0000000..e0257d2 --- /dev/null +++ b/docs/README.hdr.md @@ -0,0 +1,4 @@ +--- +hide: + - navigation +--- diff --git a/docs/assets/style.css b/docs/assets/style.css new file mode 100644 index 0000000..d7027c9 --- /dev/null +++ b/docs/assets/style.css @@ -0,0 +1,33 @@ +header { + background-image: url("https://rok4.github.io/assets/images/bandeau.png"); + background-position: top center; + background-repeat: round; +} + +.md-header__topic { + color: black; + text-shadow: 0 0 0.2em white, 0 0 0.2em white; +} + +.md-tabs { + background-color: #fff0; + color: black; + font-weight: bold; + text-shadow: 0 0 0.2em white, 0 0 0.2em white; +} + +iframe { + width: 100%; + height: 700px; + border:none; +} + +#version_menu { + position: absolute; + margin-top: -40px; +} + +#version_menu > a::before { + content: "➔"; + padding-left: 30px; +} \ No newline at end of file diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 0000000..2c2cb93 --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,9 @@ +--- +hide: + - navigation + - toc +--- + +# Documentation technique + + \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..f3a00e3 --- /dev/null +++ b/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: + - assets/style.css + +extra: + homepage: https://rok4.github.io + version: + provider: mike + default: latest \ No newline at end of file diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 0000000..7d3b2f9 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} + 🚨 Vous êtes sur la documentation d'une ancienne version. 🚨 + + Cliquez ici pour aller sur la dernière version. + +{% endblock %} \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..543b168 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +mkdocs +mkdocs-material +mike \ No newline at end of file diff --git a/docs/unit-tests.md b/docs/unit-tests.md new file mode 100644 index 0000000..5c0efa7 --- /dev/null +++ b/docs/unit-tests.md @@ -0,0 +1,9 @@ +--- +hide: + - navigation + - toc +--- + +# Rapport des tests unitaires + + \ No newline at end of file From df8bfcc080a333a98941939cd7cf07adb21ac315 Mon Sep 17 00:00:00 2001 From: Theo Satabin Date: Tue, 30 Jan 2024 09:49:05 +0100 Subject: [PATCH 2/4] Passage sur le CSS commun --- .github/workflows/build-and-release.yaml | 1 - .pre-commit-config.yaml | 2 ++ docs/assets/style.css | 33 ------------------------ docs/mkdocs.yml | 2 +- 4 files changed, 3 insertions(+), 35 deletions(-) delete mode 100644 docs/assets/style.css diff --git a/.github/workflows/build-and-release.yaml b/.github/workflows/build-and-release.yaml index 16146f0..a0348e8 100644 --- a/.github/workflows/build-and-release.yaml +++ b/.github/workflows/build-and-release.yaml @@ -100,7 +100,6 @@ jobs: pdoc3 --html --output-dir target/docs/ rok4 cp docs/mkdocs.yml target/mkdocs.yml cp -r docs/overrides target/ - cp -r docs/assets 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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f32290e..f5193ef 100644 --- a/.pre-commit-config.yaml +++ b/.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: @@ -51,3 +52,4 @@ ci: autofix_prs: true autoupdate_commit_msg: "[pre-commit.ci] Mise à jour des git hooks." autoupdate_schedule: quarterly + diff --git a/docs/assets/style.css b/docs/assets/style.css deleted file mode 100644 index d7027c9..0000000 --- a/docs/assets/style.css +++ /dev/null @@ -1,33 +0,0 @@ -header { - background-image: url("https://rok4.github.io/assets/images/bandeau.png"); - background-position: top center; - background-repeat: round; -} - -.md-header__topic { - color: black; - text-shadow: 0 0 0.2em white, 0 0 0.2em white; -} - -.md-tabs { - background-color: #fff0; - color: black; - font-weight: bold; - text-shadow: 0 0 0.2em white, 0 0 0.2em white; -} - -iframe { - width: 100%; - height: 700px; - border:none; -} - -#version_menu { - position: absolute; - margin-top: -40px; -} - -#version_menu > a::before { - content: "➔"; - padding-left: 30px; -} \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f3a00e3..a8c5c53 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -19,7 +19,7 @@ theme: custom_dir: overrides extra_css: - - assets/style.css + - https://rok4.github.io/assets/css/commun.css extra: homepage: https://rok4.github.io From 849f0fe65dd5b6114449a9724ca5c8e1f0e5b570 Mon Sep 17 00:00:00 2001 From: Theo Satabin Date: Tue, 30 Jan 2024 15:04:09 +0100 Subject: [PATCH 3/4] Correction des URLS pour pypi --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 9731107..3e9fcf9 100644 --- a/pyproject.toml +++ b/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] From 42f6fcb05e10d372013a4a081db6f5503b6243b0 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 30 Jan 2024 14:06:15 +0000 Subject: [PATCH 4/4] =?UTF-8?q?[pre-commit.ci]=20Corrections=20automatique?= =?UTF-8?q?s=20appliqu=C3=A9es=20par=20les=20git=20hooks.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .pre-commit-config.yaml | 1 - docs/documentation.md | 2 +- docs/mkdocs.yml | 2 +- docs/overrides/main.html | 4 ++-- docs/requirements.txt | 2 +- docs/unit-tests.md | 2 +- 6 files changed, 6 insertions(+), 7 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f5193ef..22c6fbc 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -52,4 +52,3 @@ ci: autofix_prs: true autoupdate_commit_msg: "[pre-commit.ci] Mise à jour des git hooks." autoupdate_schedule: quarterly - diff --git a/docs/documentation.md b/docs/documentation.md index 2c2cb93..59f441e 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -6,4 +6,4 @@ hide: # Documentation technique - \ No newline at end of file + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a8c5c53..a173ee6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -25,4 +25,4 @@ extra: homepage: https://rok4.github.io version: provider: mike - default: latest \ No newline at end of file + default: latest diff --git a/docs/overrides/main.html b/docs/overrides/main.html index 7d3b2f9..7c55859 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -2,7 +2,7 @@ {% block outdated %} 🚨 Vous êtes sur la documentation d'une ancienne version. 🚨 - + Cliquez ici pour aller sur la dernière version. -{% endblock %} \ No newline at end of file +{% endblock %} diff --git a/docs/requirements.txt b/docs/requirements.txt index 543b168..f5f7010 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ mkdocs mkdocs-material -mike \ No newline at end of file +mike diff --git a/docs/unit-tests.md b/docs/unit-tests.md index 5c0efa7..091c6bd 100644 --- a/docs/unit-tests.md +++ b/docs/unit-tests.md @@ -6,4 +6,4 @@ hide: # Rapport des tests unitaires - \ No newline at end of file +