diff --git a/.github/workflows/CheckCodeQuality.yml b/.github/workflows/CheckCodeQuality.yml index b62dcfc..d3cdd05 100644 --- a/.github/workflows/CheckCodeQuality.yml +++ b/.github/workflows/CheckCodeQuality.yml @@ -35,14 +35,29 @@ on: default: '3.13' type: string package_directory: - description: '.' + description: 'The package''s directory' required: true type: string requirements: - description: '' + description: 'Python dependencies to be installed through pip.' required: false default: '-r requirements.txt' type: string + bandit: + description: 'Run bandit checks.' + required: false + default: 'true' + type: string + radon: + description: 'Run radon checks.' + required: false + default: 'true' + type: string + pylint: + description: 'Run pylint checks.' + required: false + default: 'true' + type: string artifact: description: 'Name of the package artifact.' required: true @@ -52,6 +67,7 @@ jobs: Bandit: name: 🚨 Security Scanning (Bandit) runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}" + if: inputs.bandit == 'true' steps: - name: ⏬ Checkout repository @@ -74,9 +90,18 @@ jobs: mkdir -p report/bandit bandit -c pyproject.toml -r ${{ inputs.package_directory }} -f xml -o report/bandit/report.xml + - name: 📊 Publish Bandit Results + uses: dorny/test-reporter@v2 + continue-on-error: true + with: + name: 'Bandit Results' + path: 'report/bandit/report.xml' + reporter: java-junit + Radon: name: ☢️ Metrics and Complexity runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}" + if: inputs.radon == 'true' steps: - name: ⏬ Checkout repository @@ -116,6 +141,7 @@ jobs: PyLint: name: 🩺 Linting runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}" + if: inputs.pylint == 'true' steps: - name: ⏬ Checkout repository diff --git a/doc/Action/Releaser.rst b/doc/Action/Releaser.rst index 189a2f5..36b17ba 100644 --- a/doc/Action/Releaser.rst +++ b/doc/Action/Releaser.rst @@ -1,4 +1,6 @@ .. _ACTION/Releaser: +.. index:: + single: GitHub Action; Releaser Releaser ######## diff --git a/doc/Action/With-post-step.rst b/doc/Action/With-post-step.rst index f384445..9f4f3c5 100644 --- a/doc/Action/With-post-step.rst +++ b/doc/Action/With-post-step.rst @@ -1,4 +1,6 @@ .. _ACTION/WithPostStep: +.. index:: + single: GitHub Action; WithPostStep with-post-step ############## diff --git a/doc/Action/index.rst b/doc/Action/index.rst index 6b38509..8fb30a6 100644 --- a/doc/Action/index.rst +++ b/doc/Action/index.rst @@ -1,4 +1,6 @@ .. _ACTION: +.. index:: + single: GitHub Action Overview ######## @@ -9,6 +11,8 @@ The following 2 actions are provided by **Actions**: .. _ACTION/Instantiation: +.. index:: + single: GitHub Action; Instantiation Instantiation ************* diff --git a/doc/Glossary.rst b/doc/Glossary.rst new file mode 100644 index 0000000..aa91541 --- /dev/null +++ b/doc/Glossary.rst @@ -0,0 +1,128 @@ +Glossary +######## + +.. glossary:: + + Bandit + Bandit is a tool designed to find common security issues in Python code. + + :Source Code: `https://github.com/PyCQA/bandit/`__ + :Package: `https://pypi.org/project/bandit/`__ + :Documentation: `https://bandit.readthedocs.io/`__ + + build + A simple, correct Python build frontend. + + :Source Code: `https://github.com/pypa/build/`__ + :Package: `https://pypi.org/project/build/`__ + :Documentation: `https://build.pypa.io/`__ + + Codacy + .. todo:: Add description of Codacy. + + :Service: `Codacy.com `__ + + CodeCov + .. todo:: Add description of CodeCov. + + :Service: `Codecov.io `__ + + Coverage.py + The code coverage tool for Python. + + :Source Code: `https://github.com/nedbat/coveragepy/`__ + :Package: `https://pypi.org/project/coverage/`__ + :Documentation: `https://coverage.readthedocs.io/`__ + + delete-artifact + A GitHub Action to deletes artifacts within the workflow run. + + :Source Code: `https://github.com/GeekyEggo/delete-artifact/`__ + :Marketplace: `https://github.com/marketplace/actions/delete-artifact/`__ + :README: `https://github.com/GeekyEggo/delete-artifact/blob/main/README.md`__ + + docstr_coverage + Docstring coverage analysis and rating for Python. + + :Source Code: `https://github.com/HunterMcGushion/docstr_coverage/`__ + :Package: `https://pypi.org/project/docstr_coverage/`__ + :Documentation: `https://docstr-coverage.readthedocs.io/`__ + + gh + GitHub’s official command line tool. + + :Source Code: `https://github.com/cli/cli/`__ + :Documentation: `https://cli.github.com/manual/`__ + + GitHub Pages + GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository + on GitHub, optionally runs the files through a build process, and publishes a website. + + :Documentation: https://docs.github.com/en/pages + + interrogate + Explain yourself! Interrogate a codebase for docstring coverage. + + :Source Code: `https://github.com/econchick/interrogate/`__ + :Package: `https://pypi.org/project/interrogate/`__ + :Documentation: `https://interrogate.readthedocs.io/`__ + + MikTeX + MiKTeX is a modern TeX distribution for Windows, Linux and macOS. + + :Source Code: `https://github.com/MiKTeX/miktex/`__ + :Documentation: `https://miktex.org/`__ + + mypy + Optional static typing for Python. + + :Source Code: `https://github.com/python/mypy/`__ + :Package: `https://pypi.org/project/mypy/`__ + :Documentation: `https://www.mypy-lang.org/`__ + + pyEDAA.Reports + A collection of various (EDA tool-specific) report data formats. + + :Source Code: `https://github.com/edaa-org/pyEDAA.Reports/`__ + :Package: `https://pypi.org/project/pyEDAA.Reports/`__ + :Documentation: `https://edaa-org.github.io/pyEDAA.Reports/`__ + + pip + The Python package installer. + + :Source Code: `https://github.com/pypa/pip/`__ + :Package: `https://pypi.org/project/pip/`__ + :Documentation: `https://pip.pypa.io/`__ + + PyPI + Find, install and publish Python packages with the Python Package Index. + + :URL: `PyPI.org `__ + + pytest + The pytest framework makes it easy to write small tests, yet scales to support complex functional testing. + + :Source Code: `https://github.com/pytest-dev/pytest/`__ + :Package: `https://pypi.org/project/pytest/`__ + :Documentation: `https://pytest.org/`__ + + Sphinx + The Sphinx documentation generator. + + :Source Code: `https://github.com/sphinx-doc/sphinx/`__ + :Package: `https://pypi.org/project/sphinx/`__ + :Documentation: `https://www.sphinx-doc.org/`__ + + Test Reporter + Displays test results from popular testing frameworks directly in GitHub. + + :Source Code: `https://github.com/dorny/test-reporter/`__ + :Marketplace: `https://github.com/marketplace/actions/test-reporter/`__ + :README: `https://github.com/dorny/test-reporter/blob/main/README.md`__ + + twine + Utilities for interacting with PyPI. + + :Source Code: `https://github.com/pypa/twine/`__ + :Package: `https://pypi.org/project/twine/`__ + :Documentation: `https://twine.readthedocs.io/`__ diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index d68e933..1c003d5 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -1,4 +1,22 @@ .. _JOBTMPL/CompletePipeline: +.. index:: + single: build; CompletePipeline Template + single: Bandit; CompletePipeline Template + single: CodeCov; CompletePipeline Template + single: Codacy; CompletePipeline Template + single: Coverage.py; CompletePipeline Template + single: docstr_coverage; CompletePipeline Template + single: GitHub Pages; CompletePipeline Template + single: interrogate; CompletePipeline Template + single: MikTeX; CompletePipeline Template + single: mypy; CompletePipeline Template + single: PyPI; CompletePipeline Template + single: pytest; CompletePipeline Template + single: pyEDAA.Reports; CompletePipeline Template + single: Sphinx; CompletePipeline Template + single: Test Reporter; CompletePipeline Template + single: twine; CompletePipeline Template + single: GitHub Action Reusable Workflow; CompletePipeline Template CompletePipeline ################ @@ -16,56 +34,57 @@ It can be used for simple Python packages as well as namespace packages. .. rubric:: Testing - * Run unit tests. - * Run platform tests. - * Run application tests on target platform. + * Run unit tests before packaging using :term:`pytest`. + * Run platform tests before packaging using :term:`pytest`. + * Run application tests using packaged code on target platform. .. rubric:: Code Quality - * Collect code coverage. - * Check documentation coverage. - * Check static typing closure. + * Collect code coverage using :term:`Coverage.py`. + * Check documentation coverage using :term:`docstr_coverage` and :term:`interrogate`. + * Check static typing closure using :term:`mypy`. + * Static Application Security Testing (SAST) using :term:`bandit` .. rubric:: Report Handling - * Merge unit test results into a single summary report. - * Merge code coverage results into a single summary report. + * Merge unit test results into one report using :term:`pyEDAA.Reports`. + * Merge code coverage results into one report using :term:`Coverage.py`. .. grid-item:: :columns: 4 .. rubric:: Documentation - * Compile documentation using Sphinx as HTML and LaTeX. - * Translate LaTeX documentation to PDF. + * Compile documentation using :term:`Sphinx` as HTML and LaTeX. + * Translate LaTeX documentation to PDF using :term:`MikTeX`. .. rubric:: Publishing Results * GitHub Pipeline Summary - * Publish unittest results using :gh:`dorny/test-reporter`. + * Publish unittest results using :term:`Test Reporter`. - * GitHub Pages + * :term:`GitHub Pages` * Publish HTML documentation to GitHub Pages. - * Codacy - - * Publish code coverage to Codacy. - - * CodeCov + * :term:`Codecov` * Publish code coverage to CodeCov. * Publish unittest results to CodeCov. + * :term:`Codacy` + + * Publish code coverage to Codacy. + .. grid-item:: :columns: 4 .. rubric:: Packaging - * Package as wheel. - * Install wheel on target platform. - * Upload to PyPI. + * Package as wheel using :term:`build`. + * Install wheel on target platform using pip. + * Upload to PyPI using :term:`twine`. .. rubric:: Releasing diff --git a/doc/JobTemplate/AllInOne/index.rst b/doc/JobTemplate/AllInOne/index.rst index 4671c20..84104ed 100644 --- a/doc/JobTemplate/AllInOne/index.rst +++ b/doc/JobTemplate/AllInOne/index.rst @@ -14,7 +14,7 @@ Such a all-in-one workflow template covers: * pulishing of unit test and code coverage results * merging of test reports * packaging as wheel -* publishing wheels tp PyPI +* publishing wheels to PyPI * documentation generation via Sphinx and Miktex * automatic tagging of release commits * releasing diff --git a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst index 249c8fb..656f6a6 100644 --- a/doc/JobTemplate/Cleanup/ArtifactCleanup.rst +++ b/doc/JobTemplate/Cleanup/ArtifactCleanup.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/ArtifactCleanup: +.. index:: + single: delete-artifact; ArtifactCleanUp Template + single: GitHub Action Reusable Workflow; ArtifactCleanUp Template ArtifactCleanUp ############### diff --git a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst index f2ce9ac..88142df 100644 --- a/doc/JobTemplate/Cleanup/IntermediateCleanup.rst +++ b/doc/JobTemplate/Cleanup/IntermediateCleanup.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/IntermediateCleanUp: +.. index:: + single: delete-artifact; IntermediateCleanUp Template + single: GitHub Action Reusable Workflow; IntermediateCleanUp Template IntermediateCleanUp ################### diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index 58edeea..958670b 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/LaTeXDocumentation: +.. index:: + single: MikTeX; LaTeXDocumentation Template + single: GitHub Action Reusable Workflow; LaTeXDocumentation Template LaTeXDocumentation ################## diff --git a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst index 671aa99..ad5fa19 100644 --- a/doc/JobTemplate/Documentation/PublishToGitHubPages.rst +++ b/doc/JobTemplate/Documentation/PublishToGitHubPages.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/PublishToGitHubPages: +.. index:: + single: GitHub Pages; PublishToGitHubPages Template + single: GitHub Action Reusable Workflow; PublishToGitHubPages Template PublishToGitHubPages #################### diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index 9cf2b80..7e1a23b 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/SphinxDocumentation: +.. index:: + single: Sphinx; SphinxDocumentation Template + single: GitHub Action Reusable Workflow; SphinxDocumentation Template SphinxDocumentation ################### diff --git a/doc/JobTemplate/Package/InstallPackage.rst b/doc/JobTemplate/Package/InstallPackage.rst index f97b5db..0262abb 100644 --- a/doc/JobTemplate/Package/InstallPackage.rst +++ b/doc/JobTemplate/Package/InstallPackage.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/InstallPackage: +.. index:: + single: pip; InstallPackage Template + single: GitHub Action Reusable Workflow; InstallPackage Template InstallPackage (beta) ##################### diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index 3caffc2..2e2cf3c 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/Package: +.. index:: + single: build; Package Template + single: GitHub Action Reusable Workflow; Package Template Package ####### diff --git a/doc/JobTemplate/Package/PublishOnPyPI.rst b/doc/JobTemplate/Package/PublishOnPyPI.rst index 62e7cd2..16f0fb3 100644 --- a/doc/JobTemplate/Package/PublishOnPyPI.rst +++ b/doc/JobTemplate/Package/PublishOnPyPI.rst @@ -1,4 +1,8 @@ .. _JOBTMPL/PublishOnPyPI: +.. index:: + single: PyPI; PublishOnPyPI Template + single: twine; PublishOnPyPI Template + single: GitHub Action Reusable Workflow; PublishOnPyPI Template PublishOnPyPI ############# diff --git a/doc/JobTemplate/Publish/PublishCoverageResults.rst b/doc/JobTemplate/Publish/PublishCoverageResults.rst index 5865b77..9b7f0a7 100644 --- a/doc/JobTemplate/Publish/PublishCoverageResults.rst +++ b/doc/JobTemplate/Publish/PublishCoverageResults.rst @@ -1,4 +1,9 @@ .. _JOBTMPL/PublishCoverageResults: +.. index:: + single: CodeCov; PublishCoverageResults Template + single: Codacy; PublishCoverageResults Template + single: Coverage.py; PublishCoverageResults Template + single: GitHub Action Reusable Workflow; PublishCoverageResults Template PublishCoverageResults ###################### diff --git a/doc/JobTemplate/Publish/PublishTestResults.rst b/doc/JobTemplate/Publish/PublishTestResults.rst index 5b4ecdf..725acb4 100644 --- a/doc/JobTemplate/Publish/PublishTestResults.rst +++ b/doc/JobTemplate/Publish/PublishTestResults.rst @@ -1,4 +1,9 @@ .. _JOBTMPL/PublishTestResults: +.. index:: + single: CodeCov; PublishTestResults Template + single: pyEDAA.Reports; PublishTestResults Template + single: Test Reporter; PublishTestResults Template + single: GitHub Action Reusable Workflow; PublishTestResults Template PublishTestResults ################## diff --git a/doc/JobTemplate/Quality/CheckDocumentation.rst b/doc/JobTemplate/Quality/CheckDocumentation.rst index 3a1ba73..6cadf93 100644 --- a/doc/JobTemplate/Quality/CheckDocumentation.rst +++ b/doc/JobTemplate/Quality/CheckDocumentation.rst @@ -1,4 +1,8 @@ .. _JOBTMPL/CheckDocumentation: +.. index:: + single: docstr_coverage; CheckDocumentation Template + single: interrogate; CheckDocumentation Template + single: GitHub Action Reusable Workflow; CheckDocumentation Template CheckDocumentation ################## diff --git a/doc/JobTemplate/Quality/StaticTypeCheck.rst b/doc/JobTemplate/Quality/StaticTypeCheck.rst index caa6dba..ca621ca 100644 --- a/doc/JobTemplate/Quality/StaticTypeCheck.rst +++ b/doc/JobTemplate/Quality/StaticTypeCheck.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/StaticTypeCheck: +.. index:: + single: mypy; StaticTypeCheck Template + single: GitHub Action Reusable Workflow; StaticTypeCheck Template StaticTypeCheck ############### diff --git a/doc/JobTemplate/Release/PublishReleaseNotes.rst b/doc/JobTemplate/Release/PublishReleaseNotes.rst index 08038d8..36e8372 100644 --- a/doc/JobTemplate/Release/PublishReleaseNotes.rst +++ b/doc/JobTemplate/Release/PublishReleaseNotes.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/PublishReleaseNotes: +.. index:: + single: gh; PublishReleaseNotes Template + single: GitHub Action Reusable Workflow; PublishReleaseNotes Template PublishReleaseNotes ################### diff --git a/doc/JobTemplate/Release/TagReleaseCommit.rst b/doc/JobTemplate/Release/TagReleaseCommit.rst index 22cff04..c280f4c 100644 --- a/doc/JobTemplate/Release/TagReleaseCommit.rst +++ b/doc/JobTemplate/Release/TagReleaseCommit.rst @@ -1,4 +1,7 @@ .. _JOBTMPL/TagReleaseCommit: +.. index:: + single: gh; TagReleaseCommit Template + single: GitHub Action Reusable Workflow; TagReleaseCommit Template TagReleaseCommit ################ diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index 122937a..6b7db0c 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -1,4 +1,6 @@ .. _JOBTMPL/ExtractConfiguration: +.. index:: + single: GitHub Action Reusable Workflow; ExtractConfiguration Template ExtractConfiguration #################### diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index 9eb074c..46d8033 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -1,4 +1,6 @@ .. _JOBTMPL/Parameters: +.. index:: + single: GitHub Action Reusable Workflow; Parameters Template Parameters ########## diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 6874971..615d806 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -1,4 +1,6 @@ .. _JOBTMPL/PrepareJob: +.. index:: + single: GitHub Action Reusable Workflow; PrepareJob Template PrepareJob ########## diff --git a/doc/JobTemplate/Testing/UnitTesting.rst b/doc/JobTemplate/Testing/UnitTesting.rst index 9eb522d..f63c123 100644 --- a/doc/JobTemplate/Testing/UnitTesting.rst +++ b/doc/JobTemplate/Testing/UnitTesting.rst @@ -1,4 +1,8 @@ .. _JOBTMPL/UnitTesting: +.. index:: + single: pytest; UnitTesting Template + single: Coverage.py; UnitTesting Template + single: GitHub Action Reusable Workflow; UnitTesting Template UnitTesting ########### diff --git a/doc/JobTemplate/index.rst b/doc/JobTemplate/index.rst index 099fe29..8037a99 100644 --- a/doc/JobTemplate/index.rst +++ b/doc/JobTemplate/index.rst @@ -1,4 +1,6 @@ .. _JOBTMPL: +.. index:: + single: GitHub Action Reusable Workflow Overview ######## @@ -11,6 +13,8 @@ customizable. .. _JOBTMPL/Instantiation: +.. index:: + single: GitHub Action Reusable Workflow; Instantiation Instantiation ************* @@ -56,6 +60,8 @@ Some templates might provide output parameters, which can be used in dependent j .. _JOBTMPL/CommonParameters: +.. index:: + single: GitHub Action Reusable Workflow; Common Parameters Common Parameters ***************** diff --git a/doc/conf.py b/doc/conf.py index 7f2c9a1..9c6b841 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -220,6 +220,7 @@ extlinks = { "ghsrc": (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None), "wiki": (f"https://en.wikipedia.org/wiki/%s", None), "pypi": (f"https://pypi.org/project/%s/", "PyPI: %s"), + "rtd": (f"https://%s.readthedocs.io/", "RTD: %s"), "ucrt64": (f"https://packages.msys2.org/packages/mingw-w64-ucrt-x86_64-%s", "UCRT64: %s"), "dockerhub": (f"https://hub.docker.com/r/%s", "Docker Hub: %s"), } diff --git a/doc/index.rst b/doc/index.rst index 383e491..08291db 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -317,4 +317,6 @@ License License Doc-License + Glossary + genindex TODO