From c924651632013a959752807bc17b74059613b552 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 3 Nov 2024 08:42:32 +0100 Subject: [PATCH] Split Sphinx into a prepare and two working sub-jobs for HTML and LaTeX. --- .github/workflows/SphinxDocumentation.yml | 102 ++++++++++++++++++---- .github/workflows/_Checking_Pipeline.yml | 32 +++---- 2 files changed, 101 insertions(+), 33 deletions(-) diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml index 6fe793b..3d74408 100644 --- a/.github/workflows/SphinxDocumentation.yml +++ b/.github/workflows/SphinxDocumentation.yml @@ -24,6 +24,11 @@ name: Documentation on: workflow_call: inputs: + ubuntu_image_version: + description: 'Ubuntu image version.' + required: false + default: '24.04' + type: string python_version: description: 'Python version.' required: false @@ -71,17 +76,20 @@ on: type: string jobs: - Sphinx: - name: 📓 Documentation generation using Sphinx and Python ${{ inputs.python_version }} - runs-on: ubuntu-24.04 + Prepare: + name: 📓 Extract configurations from pyproject.toml + runs-on: "ubuntu-${ubuntu_image_version}" + outputs: + coverage_report_html_directory: ${{ steps.getVariables.outputs.coverage_report_html_directory }} + coverage_report_xml_directory: ${{ steps.getVariables.outputs.coverage_report_xml_directory }} + coverage_report_xml: ${{ steps.getVariables.outputs.coverage_report_xml }} + coverage_report_json_directory: ${{ steps.getVariables.outputs.coverage_report_json_directory }} + coverage_report_json: ${{ steps.getVariables.outputs.coverage_report_json }} steps: - name: ⏬ Checkout repository uses: actions/checkout@v4 - - name: 🔧 Install graphviz - run: sudo apt-get install -y --no-install-recommends graphviz - - name: 🐍 Setup Python ${{ inputs.python_version }} uses: actions/setup-python@v5 with: @@ -154,6 +162,29 @@ jobs: print(f"DEBUG:\n html={htmlDirectory}\n xml={xmlFile}\n json={jsonFile}") + Sphinx-HTML: + name: 📓 Documentation generation using Sphinx and Python ${{ inputs.python_version }} + runs-on: "ubuntu-${ubuntu_image_version}" + needs: + - Prepare + + steps: + - name: ⏬ Checkout repository + uses: actions/checkout@v4 + + - name: 🔧 Install graphviz + run: sudo apt-get install -y --no-install-recommends graphviz + + - name: 🐍 Setup Python ${{ inputs.python_version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ inputs.python_version }} + + - name: 🔧 Install wheel,tomli and pip dependencies (native) + run: | + python -m pip install --disable-pip-version-check -U wheel + python -m pip install --disable-pip-version-check ${{ inputs.requirements }} + - name: 📥 Download artifacts '${{ inputs.unittest_xml_artifact }}' from 'Unittesting' job if: inputs.unittest_xml_artifact != '' uses: actions/download-artifact@v4 @@ -166,7 +197,7 @@ jobs: uses: actions/download-artifact@v4 with: name: ${{ inputs.coverage_json_artifact }} - path: ${{ steps.getVariables.outputs.coverage_report_json_directory }} + path: ${{ needs.Prepare.outputs.coverage_report_json_directory }} - name: ☑ Generate HTML documentation if: inputs.html_artifact != '' @@ -176,16 +207,6 @@ jobs: cd "${{ inputs.doc_directory || '.' }}" sphinx-build -v -n -b html -d _build/doctrees -j $(nproc) -w _build/html.log . _build/html - - name: ☑ Generate LaTeX documentation - if: inputs.latex_artifact != '' -# continue-on-error: true - run: | - export PYTHONPATH=$(pwd) - - cd "${{ inputs.doc_directory || '.' }}" - sphinx-build -v -n -b latex -d _build/doctrees -j $(nproc) -w _build/latex.log . _build/latex -# --builder html --doctree-dir _build/doctrees --verbose --fresh-env --write-all --nitpicky --warning-file _build/html.log . _build/html - - name: 📤 Upload 'HTML Documentation' artifact if: inputs.html_artifact != '' continue-on-error: true @@ -196,6 +217,53 @@ jobs: if-no-files-found: error retention-days: 1 + Sphinx-LaTeX: + name: 📓 Documentation generation using Sphinx and Python ${{ inputs.python_version }} + runs-on: "ubuntu-${ubuntu_image_version}" + needs: + - Prepare + + steps: + - name: ⏬ Checkout repository + uses: actions/checkout@v4 + + - name: 🔧 Install graphviz + run: sudo apt-get install -y --no-install-recommends graphviz + + - name: 🐍 Setup Python ${{ inputs.python_version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ inputs.python_version }} + + - name: 🔧 Install wheel,tomli and pip dependencies (native) + run: | + python -m pip install --disable-pip-version-check -U wheel + python -m pip install --disable-pip-version-check ${{ inputs.requirements }} + + - name: 📥 Download artifacts '${{ inputs.unittest_xml_artifact }}' from 'Unittesting' job + if: inputs.unittest_xml_artifact != '' + uses: actions/download-artifact@v4 + with: + name: ${{ inputs.unittest_xml_artifact }} + path: ${{ inputs.unittest_xml_directory }} + + - name: 📥 Download artifacts '${{ inputs.coverage_json_artifact }}' from 'PublishCoverageResults' job + if: inputs.coverage_json_artifact != '' + uses: actions/download-artifact@v4 + with: + name: ${{ inputs.coverage_json_artifact }} + path: ${{ needs.Prepare.outputs.coverage_report_json_directory }} + + - name: ☑ Generate LaTeX documentation + if: inputs.latex_artifact != '' +# continue-on-error: true + run: | + export PYTHONPATH=$(pwd) + + cd "${{ inputs.doc_directory || '.' }}" + sphinx-build -v -n -b latex -d _build/doctrees -j $(nproc) -w _build/latex.log . _build/latex +# --builder html --doctree-dir _build/doctrees --verbose --fresh-env --write-all --nitpicky --warning-file _build/html.log . _build/html + - name: 📤 Upload 'LaTeX Documentation' artifact if: inputs.latex_artifact != '' continue-on-error: true diff --git a/.github/workflows/_Checking_Pipeline.yml b/.github/workflows/_Checking_Pipeline.yml index dba6805..d418fe9 100644 --- a/.github/workflows/_Checking_Pipeline.yml +++ b/.github/workflows/_Checking_Pipeline.yml @@ -6,21 +6,21 @@ on: jobs: UnitTestingParams: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev + uses: pyTooling/Actions/.github/workflows/Parameters.yml@sphinx with: name: pyDummy python_version_list: "3.8 3.9 3.10 3.11 3.12 3.13 pypy-3.8 pypy-3.9 pypy-3.10" # disable_list: "windows:pypy-3.10" PlatformTestingParams: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev + uses: pyTooling/Actions/.github/workflows/Parameters.yml@sphinx with: name: Platform python_version_list: "" system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64" UnitTesting: - uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@sphinx needs: - UnitTestingParams with: @@ -33,7 +33,7 @@ jobs: # coverage_html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_html }} PlatformTesting: - uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@sphinx needs: - PlatformTestingParams with: @@ -48,7 +48,7 @@ jobs: coverage_html_artifact: ${{ fromJson(needs.PlatformTestingParams.outputs.artifact_names).codecoverage_html }} # Coverage: -# uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev +# uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@sphinx # needs: # - UnitTestingParams # with: @@ -58,7 +58,7 @@ jobs: # codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} StaticTypeCheck: - uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@dev + uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@sphinx needs: - UnitTestingParams with: @@ -69,7 +69,7 @@ jobs: html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).statictyping_html }} PublishCoverageResults: - uses: pyTooling/Actions/.github/workflows/PublishCoverageResults.yml@dev + uses: pyTooling/Actions/.github/workflows/PublishCoverageResults.yml@sphinx needs: - UnitTestingParams - UnitTesting @@ -84,7 +84,7 @@ jobs: codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }} PublishTestResults: - uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@dev + uses: pyTooling/Actions/.github/workflows/PublishTestResults.yml@sphinx needs: - UnitTesting - PlatformTesting @@ -92,7 +92,7 @@ jobs: additional_merge_args: '-d "--pytest=rewrite-dunder-init;reduce-depth:pytest.tests.unit;reduce-depth:pytest.tests.platform"' Package: - uses: pyTooling/Actions/.github/workflows/Package.yml@dev + uses: pyTooling/Actions/.github/workflows/Package.yml@sphinx needs: - UnitTestingParams - UnitTesting @@ -103,14 +103,14 @@ jobs: artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).package_all }} # VerifyDocs: -# uses: pyTooling/Actions/.github/workflows/VerifyDocs.yml@dev +# uses: pyTooling/Actions/.github/workflows/VerifyDocs.yml@sphinx # needs: # - UnitTestingParams # with: # python_version: ${{ needs.UnitTestingParams.outputs.python_version }} HTMLDocumentation: - uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@dev + uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@sphinx needs: - UnitTestingParams # - VerifyDocs @@ -122,7 +122,7 @@ jobs: latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }} PDFDocumentation: - uses: pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml@r1 + uses: pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml@sphinx needs: - UnitTestingParams - HTMLDocumentation @@ -132,7 +132,7 @@ jobs: pdf_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }} PublishToGitHubPages: - uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@dev + uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@sphinx needs: - UnitTestingParams - HTMLDocumentation @@ -146,7 +146,7 @@ jobs: typing: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).statictyping_html }} ReleasePage: - uses: pyTooling/Actions/.github/workflows/Release.yml@dev + uses: pyTooling/Actions/.github/workflows/Release.yml@sphinx if: startsWith(github.ref, 'refs/tags') needs: - UnitTesting @@ -157,7 +157,7 @@ jobs: - PublishToGitHubPages PublishOnPyPI: - uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@dev + uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@sphinx if: startsWith(github.ref, 'refs/tags') needs: - UnitTestingParams @@ -171,7 +171,7 @@ jobs: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} ArtifactCleanUp: - uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@dev + uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@sphinx needs: - UnitTestingParams - PlatformTestingParams