From cf6fbd4d8e4bcf6cbd2acaf55614abe023d7c615 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 11 Jan 2024 17:46:03 +0100 Subject: [PATCH 1/6] Added new SphinxDocumentation workflow template. --- .github/workflows/SphinxDocumentation.yml | 122 ++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 .github/workflows/SphinxDocumentation.yml diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml new file mode 100644 index 0000000..be9abbf --- /dev/null +++ b/.github/workflows/SphinxDocumentation.yml @@ -0,0 +1,122 @@ +# ==================================================================================================================== # +# Authors: # +# Patrick Lehmann # +# # +# ==================================================================================================================== # +# Copyright 2020-2024 The pyTooling Authors # +# # +# Licensed under the Apache License, Version 2.0 (the "License"); # +# you may not use this file except in compliance with the License. # +# You may obtain a copy of the License at # +# # +# http://www.apache.org/licenses/LICENSE-2.0 # +# # +# Unless required by applicable law or agreed to in writing, software # +# distributed under the License is distributed on an "AS IS" BASIS, # +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # +# See the License for the specific language governing permissions and # +# limitations under the License. # +# # +# SPDX-License-Identifier: Apache-2.0 # +# ==================================================================================================================== # +name: Documentation + +on: + workflow_call: + inputs: + python_version: + description: 'Python version.' + required: false + default: '3.12' + type: string + requirements: + description: 'Python dependencies to be installed through pip.' + required: false + default: '-r doc/requirements.txt' + type: string + doc_directory: + description: 'Path to the directory containing documentation (Sphinx working directory).' + required: false + default: 'doc' + type: string + html_artifact: + description: 'Name of the HTML documentation artifact.' + required: false + default: '' + type: string + latex_artifact: + description: 'Name of the LaTeX documentation artifact.' + required: false + default: '' + type: string + coverage_html_artifact: + description: 'Name of the HTML coverage artifact.' + required: false + default: '' + type: string + +jobs: + Sphinx: + name: 📓 Documentation generation using Sphinx and Python ${{ inputs.python_version }} + runs-on: ubuntu-latest + + steps: + - name: ⏬ Checkout repository + uses: actions/checkout@v4 + + - name: 📥 Download artifacts '${{ inputs.artifact }}' from 'Package' job + if: inputs.coverage_html_artifact != '' + uses: actions/download-artifact@v4 + with: + name: ${{ inputs.coverage_html_artifact }} + + - name: 🐍 Setup Python ${{ inputs.python_version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + + - name: 🔧 Install wheel,tomli and pip dependencies (native) + run: | + # python -m pip install --disable-pip-version-check -U wheel tomli + python -m pip install --disable-pip-version-check ${{ inputs.requirements }} + + - name: ☑ Generate HTML documentation + if: inputs.html_artifact != '' + run: | + export PYTHONPATH=$(pwd) + + ls -lah . + ls -lah report + + 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 + uses: actions/upload-artifact@v4 + with: + name: ${{ inputs.html_artifact }} + path: ${{ inputs.doc_directory }}/_build/html + if-no-files-found: error + retention-days: 1 + + - name: 📤 Upload 'LaTeX Documentation' artifact + if: inputs.latex_artifact != '' + continue-on-error: true + uses: actions/upload-artifact@v4 + with: + name: ${{ inputs.latex_artifact }} + path: ${{ inputs.doc_directory }}/_build/latex + if-no-files-found: error + retention-days: 1 From 0efec874630904f6881e36dcf8e378dc206d1dce Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 11 Jan 2024 20:41:57 +0100 Subject: [PATCH 2/6] Added an artifact name for intermediate LateX documentation. --- .github/workflows/Parameters.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/Parameters.yml b/.github/workflows/Parameters.yml index e803933..bc18f83 100644 --- a/.github/workflows/Parameters.yml +++ b/.github/workflows/Parameters.yml @@ -245,8 +245,9 @@ jobs: "codecoverage_html": f"{name}-CodeCoverage-HTML", "statictyping_html": f"{name}-StaticTyping-HTML", "package_all": f"{name}-Packages", - "documentation_pdf": f"{name}-Documentation-PDF", "documentation_html": f"{name}-Documentation-HTML", + "documentation_latex": f"{name}-Documentation-LaTeX", + "documentation_pdf": f"{name}-Documentation-PDF", } # Deprecated structure From 8a801bd851d74c221d845e7e884c96a663dfeea1 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 11 Jan 2024 21:09:20 +0100 Subject: [PATCH 3/6] Read some settings from pyproject.toml. --- .github/workflows/SphinxDocumentation.yml | 71 +++++++++++++++++++++-- 1 file changed, 65 insertions(+), 6 deletions(-) diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml index be9abbf..79dbf26 100644 --- a/.github/workflows/SphinxDocumentation.yml +++ b/.github/workflows/SphinxDocumentation.yml @@ -64,12 +64,6 @@ jobs: - name: ⏬ Checkout repository uses: actions/checkout@v4 - - name: 📥 Download artifacts '${{ inputs.artifact }}' from 'Package' job - if: inputs.coverage_html_artifact != '' - uses: actions/download-artifact@v4 - with: - name: ${{ inputs.coverage_html_artifact }} - - name: 🐍 Setup Python ${{ inputs.python_version }} uses: actions/setup-python@v5 with: @@ -80,6 +74,69 @@ jobs: # python -m pip install --disable-pip-version-check -U wheel tomli python -m pip install --disable-pip-version-check ${{ inputs.requirements }} + - name: 🔁 Extract configurations from pyproject.toml + id: getVariables + shell: python + run: | + from os import getenv + from pathlib import Path + from sys import version + from textwrap import dedent + + print(f"Python: {version}") + + from tomli import load as tomli_load + + htmlDirectory = Path("htmlcov") + xmlFile = Path("./coverage.xml") + jsonFile = Path("./coverage.json") + coverageRC = "${{ inputs.coverage_config }}".strip() + + # Read output paths from 'pyproject.toml' file + if coverageRC == "pyproject.toml": + pyProjectFile = Path("pyproject.toml") + if pyProjectFile.exists(): + with pyProjectFile.open("rb") as file: + pyProjectSettings = tomli_load(file) + + htmlDirectory = Path(pyProjectSettings["tool"]["coverage"]["html"]["directory"]) + xmlFile = Path(pyProjectSettings["tool"]["coverage"]["xml"]["output"]) + jsonFile = Path(pyProjectSettings["tool"]["coverage"]["json"]["output"]) + else: + print(f"File '{pyProjectFile}' not found and no '.coveragerc' file specified.") + + # Read output paths from '.coveragerc' file + elif len(coverageRC) > 0: + coverageRCFile = Path(coverageRC) + if coverageRCFile.exists(): + with coverageRCFile.open("rb") as file: + coverageRCSettings = tomli_load(file) + + htmlDirectory = Path(coverageRCSettings["html"]["directory"]) + xmlFile = Path(coverageRCSettings["xml"]["output"]) + jsonFile = Path(coverageRCSettings["json"]["output"]) + else: + print(f"File '{coverageRCFile}' not found.") + + # Write jobs to special file + github_output = Path(getenv("GITHUB_OUTPUT")) + print(f"GITHUB_OUTPUT: {github_output}") + with github_output.open("a+", encoding="utf-8") as f: + f.write(dedent(f"""\ + coverage_report_html_directory={htmlDirectory.as_posix()} + coverage_report_xml={xmlFile} + coverage_report_json={jsonFile} + """)) + + print(f"DEBUG:\n html={htmlDirectory}\n xml={xmlFile}\n json={jsonFile}") + + - name: 📥 Download artifacts '${{ inputs.artifact }}' from 'Package' job + if: inputs.coverage_html_artifact != '' + uses: actions/download-artifact@v4 + with: + name: ${{ inputs.coverage_html_artifact }} + path: ${{ steps.getVariables.outputs.coverage_report_html_directory }} + - name: ☑ Generate HTML documentation if: inputs.html_artifact != '' run: | @@ -87,6 +144,8 @@ jobs: ls -lah . ls -lah report + ls -lah report/coverage + ls -lah report/coverage/html cd "${{ inputs.doc_directory || '.' }}" sphinx-build -v -n -b html -d _build/doctrees -j $(nproc) -w _build/html.log . _build/html From 41e1e109c3c558e85a3501aa5ec7be323ba43813 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 11 Jan 2024 21:19:44 +0100 Subject: [PATCH 4/6] Added coverage_config parameter. --- .github/workflows/SphinxDocumentation.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml index 79dbf26..4304599 100644 --- a/.github/workflows/SphinxDocumentation.yml +++ b/.github/workflows/SphinxDocumentation.yml @@ -34,6 +34,11 @@ on: required: false default: '-r doc/requirements.txt' type: string + coverage_config: + description: 'Path to the .coveragerc file. Use pyproject.toml by default.' + required: false + default: 'pyproject.toml' + type: string doc_directory: description: 'Path to the directory containing documentation (Sphinx working directory).' required: false From 67d7ec2c73bf3fc6b1454c4e73d025f6a9b21f4e Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 11 Jan 2024 22:00:59 +0100 Subject: [PATCH 5/6] Provide GITHUB_TOKEN to cleanup step.. --- .github/workflows/ArtifactCleanUp.yml | 2 ++ .github/workflows/SphinxDocumentation.yml | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ArtifactCleanUp.yml b/.github/workflows/ArtifactCleanUp.yml index e325baa..2480577 100644 --- a/.github/workflows/ArtifactCleanUp.yml +++ b/.github/workflows/ArtifactCleanUp.yml @@ -48,9 +48,11 @@ jobs: uses: geekyeggo/delete-artifact@v4 with: name: ${{ inputs.package }} + token: ${{ secrets.GITHUB_TOKEN }} - name: 🗑️ Delete remaining Artifacts if: ${{ inputs.remaining != '' }} uses: geekyeggo/delete-artifact@v4 with: name: ${{ inputs.remaining }} + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml index 4304599..3692605 100644 --- a/.github/workflows/SphinxDocumentation.yml +++ b/.github/workflows/SphinxDocumentation.yml @@ -72,11 +72,11 @@ jobs: - name: 🐍 Setup Python ${{ inputs.python_version }} uses: actions/setup-python@v5 with: - python-version: ${{ matrix.python }} + python-version: ${{ inputs.python_version }} - name: 🔧 Install wheel,tomli and pip dependencies (native) run: | - # python -m pip install --disable-pip-version-check -U wheel tomli + python -m pip install --disable-pip-version-check -U wheel tomli python -m pip install --disable-pip-version-check ${{ inputs.requirements }} - name: 🔁 Extract configurations from pyproject.toml From 6844d48a6fe87287dbdb91a5cb17bb432ca6c4e4 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 11 Jan 2024 23:13:11 +0100 Subject: [PATCH 6/6] Install graphviz. --- .github/workflows/SphinxDocumentation.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/SphinxDocumentation.yml b/.github/workflows/SphinxDocumentation.yml index 3692605..3c84588 100644 --- a/.github/workflows/SphinxDocumentation.yml +++ b/.github/workflows/SphinxDocumentation.yml @@ -69,6 +69,9 @@ jobs: - 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: @@ -147,11 +150,6 @@ jobs: run: | export PYTHONPATH=$(pwd) - ls -lah . - ls -lah report - ls -lah report/coverage - ls -lah report/coverage/html - cd "${{ inputs.doc_directory || '.' }}" sphinx-build -v -n -b html -d _build/doctrees -j $(nproc) -w _build/html.log . _build/html