diff --git a/.github/workflows/CheckCodeQuality.yml b/.github/workflows/CheckCodeQuality.yml index d3cdd05..13af447 100644 --- a/.github/workflows/CheckCodeQuality.yml +++ b/.github/workflows/CheckCodeQuality.yml @@ -90,6 +90,10 @@ jobs: mkdir -p report/bandit bandit -c pyproject.toml -r ${{ inputs.package_directory }} -f xml -o report/bandit/report.xml + - name: Debug + run: | + cat report/bandit/report.xml + - name: 📊 Publish Bandit Results uses: dorny/test-reporter@v2 continue-on-error: true diff --git a/.github/workflows/StaticTypeCheck.yml b/.github/workflows/StaticTypeCheck.yml index 2ac647c..431d239 100644 --- a/.github/workflows/StaticTypeCheck.yml +++ b/.github/workflows/StaticTypeCheck.yml @@ -48,17 +48,28 @@ on: cobertura_report: description: 'Cobertura file to upload as an artifact.' required: false - default: '{"fullpath": "report/typing/cobertura.xml", "directory": "report/typing", "filename": "cobertura.xml"}' + default: >- + { "fullpath": "report/typing/cobertura.xml", + "directory": "report/typing", + "filename": "cobertura.xml" + } type: string junit_report: description: 'JUnit file to upload as an artifact.' required: false - default: '{"fullpath": "report/typing/StaticTypingSummary.xml", "directory": "report/typing", "filename": "StaticTypingSummary.xml"}' + default: >- + { "fullpath": "report/typing/StaticTypingSummary.xml", + "directory": "report/typing", + "filename": "StaticTypingSummary.xml" + } type: string html_report: description: 'Directory to upload as an artifact.' required: false - default: '{"fullpath": "report/typing/html", "directory": "report/typing/html"}' + default: >- + { "directory": "report/typing/html" + } +# "fullpath": "report/typing/html", type: string cobertura_artifact: description: 'Name of the typing cobertura artifact (Cobertura XML).' diff --git a/.github/workflows/UnitTesting.yml b/.github/workflows/UnitTesting.yml index 08d72a2..7b7aa6a 100644 --- a/.github/workflows/UnitTesting.yml +++ b/.github/workflows/UnitTesting.yml @@ -95,44 +95,44 @@ on: default: 'unit' type: string unittest_report_xml: - description: 'Path where to save the unittest summary report XML.' + description: 'JSON object describing the path where to save the unittest summary report XML.' required: false - default: 'report/unit' + default: >- + { "directory": "report/unit", + "filename": "TestReportSummary.xml", + "fullpath": "report/unit/TestReportSummary.xml" + } type: string -# unittest_report_xml_filename: -# description: 'Filename of the unittest summary report XML.' -# required: false -# default: 'TestReportSummary.xml' -# type: string coverage_config: description: 'Path to the .coveragerc file. Use pyproject.toml by default.' required: false default: 'pyproject.toml' type: string coverage_report_xml: - description: 'Directory where the coverage report in XML format will be generated.' + description: 'JSON object describing the path where the coverage report in XML format will be generated.' required: false - default: 'report/coverage' + default: >- + { "directory": "report/coverage", + "filename": "coverage.xml", + "fullpath": "report/coverage/coverage.xml" + } type: string -# coverage_report_xml_filename: -# description: 'Filename how the coverage report in XML format will be named.' -# required: false -# default: 'coverage.xml' -# type: string coverage_report_json: - description: 'Directory where the coverage report in JSON format will be generated.' + description: 'JSON object describing the path where the coverage report in JSON format will be generated.' required: false - default: 'report/coverage' + default: >- + { "directory": "report/coverage", + "filename": "coverage.json", + "fullpath": "report/coverage/coverage.json" + } type: string -# coverage_report_json_filename: -# description: 'Filename how the coverage report in JSON format will be named.' -# required: false -# default: 'coverage.json' -# type: string coverage_report_html: - description: 'Directory where the coverage report in HTML format will be generated.' + description: 'JSON object describing the path where the coverage report in HTML format will be generated.' required: false - default: 'report/coverage/html' + default: >- + { "directory": "report/coverage/html", + } +# "fullpath": "report/coverage/html" type: string unittest_xml_artifact: description: "Generate unit test report with junitxml and upload results as an artifact." diff --git a/doc/Glossary.rst b/doc/Glossary.rst index aa91541..f98a866 100644 --- a/doc/Glossary.rst +++ b/doc/Glossary.rst @@ -6,53 +6,53 @@ 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/`__ + :Source Code: `github.com/PyCQA/bandit/ `__ + :Package: `pypi.org/project/bandit/ `__ + :Documentation: `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/`__ + :Source Code: `github.com/pypa/build/ `__ + :Package: `pypi.org/project/build/ `__ + :Documentation: `build.pypa.io/ `__ Codacy .. todo:: Add description of Codacy. - :Service: `Codacy.com `__ + :Cloud Service: `Codacy.com `__ CodeCov .. todo:: Add description of CodeCov. - :Service: `Codecov.io `__ + :Cloud 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/`__ + :Source Code: `github.com/nedbat/coveragepy/ `__ + :Package: `pypi.org/project/coverage/ `__ + :Documentation: `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`__ + :Source Code: `github.com/GeekyEggo/delete-artifact/ `__ + :Marketplace: `github.com/marketplace/actions/delete-artifact/ `__ + :README: `github.com/GeekyEggo/delete-artifact ⭢ 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/`__ + :Source Code: `github.com/HunterMcGushion/docstr_coverage/ `__ + :Package: `pypi.org/project/docstr_coverage/ `__ + :Documentation: `docstr-coverage.readthedocs.io/ `__ gh GitHub’s official command line tool. - :Source Code: `https://github.com/cli/cli/`__ - :Documentation: `https://cli.github.com/manual/`__ + :Source Code: `github.com/cli/cli/ `__ + :Documentation: `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 @@ -63,66 +63,66 @@ Glossary 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/`__ + :Source Code: `github.com/econchick/interrogate/ `__ + :Package: `pypi.org/project/interrogate/ `__ + :Documentation: `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/`__ + :Source Code: `github.com/MiKTeX/miktex/ `__ + :Documentation: `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/`__ + :Source Code: `github.com/python/mypy/ `__ + :Package: `pypi.org/project/mypy/ `__ + :Documentation: `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/`__ + :Source Code: `github.com/edaa-org/pyEDAA.Reports/ `__ + :Package: `pypi.org/project/pyEDAA.Reports/ `__ + :Documentation: `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/`__ + :Source Code: `github.com/pypa/pip/ `__ + :Package: `pypi.org/project/pip/ `__ + :Documentation: `pip.pypa.io/ `__ PyPI Find, install and publish Python packages with the Python Package Index. - :URL: `PyPI.org `__ + :Cloud Service: `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/`__ + :Source Code: `github.com/pytest-dev/pytest/ `__ + :Package: `pypi.org/project/pytest/ `__ + :Documentation: `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/`__ + :Source Code: `github.com/sphinx-doc/sphinx/ `__ + :Package: `pypi.org/project/sphinx/ `__ + :Documentation: `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`__ + :Source Code: `github.com/dorny/test-reporter/ `__ + :Marketplace: `github.com/marketplace/actions/test-reporter/ `__ + :README: `github.com/dorny/test-reporter ⭢ 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/`__ + :Source Code: `github.com/pypa/twine/ `__ + :Package: `pypi.org/project/twine/ `__ + :Documentation: `twine.readthedocs.io/ `__ diff --git a/doc/JobTemplate/Quality/StaticTypeCheck.rst b/doc/JobTemplate/Quality/StaticTypeCheck.rst index ca621ca..ccb7f57 100644 --- a/doc/JobTemplate/Quality/StaticTypeCheck.rst +++ b/doc/JobTemplate/Quality/StaticTypeCheck.rst @@ -6,18 +6,18 @@ StaticTypeCheck ############### -This job template runs a static type check using `mypy `__ and collects the results. These -results can be converted to a HTML report and uploaded as an artifact. +This job template runs a static type check using :term:`mypy` and collects the results. These results can be converted +to a HTML report and uploaded as an artifact. .. topic:: Features - * Run static type check using mypy. + * Run static type check using :term:`mypy`. .. topic:: Behavior 1. Checkout repository 2. Setup Python and install dependencies - 3. Run type checking command(s). + 3. Run type checking. 4. Upload type checking report as an artifact .. topic:: Job Execution @@ -61,8 +61,9 @@ directory ``report/typing``. StaticTypeCheck: uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5 with: - html_report: 'htmlmpyp' - artifact: 'TypeChecking' + cobertura_artifact: 'TypeChecking-Cobertura' + junit_artifact: 'TypeChecking-JUnit' + html_artifact: 'TypeChecking-HTML' .. grid-item:: :columns: 6 @@ -74,7 +75,9 @@ directory ``report/typing``. strict = true pretty = true - html_report = "htmlmpyp" + html_report = "report/typing/html" + junit_xml = "report/typing/StaticTypingSummary.xml" + cobertura_xml_report = "report/typing" Complex Example @@ -104,8 +107,8 @@ precompute the artifact's name. - Params with: python_version: ${{ needs.Params.outputs.python_version }} - report: ${{ needs.ConfigParams.outputs.typing_report_html_directory }} - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }} + junit_report: ${{ needs.ConfigParams.outputs.typing_report_junit }} + junit_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_junit }} .. _JOBTMPL/StaticTypeCheck/Parameters: @@ -115,23 +118,29 @@ Parameter Summary .. rubric:: Goto :ref:`input parameters ` -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=====================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/ubuntu_image_version` | no | string | ``'24.04'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/python_version` | no | string | ``'3.13'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/html_report` | no | string | ``'report/typing'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_report` | no | string | ``'StaticTypingSummary.xml'`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/html_artifact` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_artifact` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=====================================================================+==========+================+==========================================================================================================================================+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/python_version` | no | string | ``'3.13'`` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/mypy_options` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/cobertura.xml", "directory": "report/typing", "filename": "cobertura.xml"}` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_report` | no | string (JSON) | :jsoncode:`{"fullpath": "report/typing/StaticTypingSummary.xml", "directory": "report/typing", "filename": "StaticTypingSummary.xml"}` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/html_report` | no | string (JSON) | :jsoncode:`{"directory": "report/typing/html"}` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/cobertura_artifact` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/junit_artifact` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/StaticTypeCheck/Input/html_artifact` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -171,16 +180,56 @@ requirements :Description: Python dependencies to be installed through *pip*. -.. _JOBTMPL/StaticTypeCheck/Input/html_report: +.. _JOBTMPL/StaticTypeCheck/Input/mypy_options: -html_report -=========== +mypy_options +============ :Type: string :Required: no -:Default Value: ``'report/typing'`` -:Possible Values: Any valid directory or subdirectory path. -:Description: The directory containing the generated HTML report. +:Default Value: ``''`` +:Possible Values: Any valid command line options for :term:`mypy`. +:Description: Additional options handed over to mypy as ``mypy ${mypy_options}``. + + +.. _JOBTMPL/StaticTypeCheck/Input/cobertura_report: + +cobertura_report +================ + +:Type: string (JSON) +:Required: no +:Default Value: + .. code-block:: json + + { "directory": "reports/typing", + "filename": "cobertura.xml", + "fullpath": "reports/typing/cobertura.xml" + } +:Possible Values: Any valid JSON string containing a JSON object with fields: + + :directory: Directory or sub-directory where the type checking report in Cobertura XML format will be + saved. + :filename: Filename of the generated type checking report in Cobertura XML format. |br| + Currently, this filename is hardcoded within :term:`mypy` as :file:`cobertura.xml`. + :fullpath: The concatenation of both previous fields using the ``/`` separator. +:Description: Directory, filename and fullpath as JSON object where the type checking report in Cobertura XML format + will be saved. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. +:Example: + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + UnitTesting: + uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5 + needs: + - ConfigParams + with: + ... + cobertura_report: ${{ needs.ConfigParams.outputs.statictyping_cobertura }} .. _JOBTMPL/StaticTypeCheck/Input/junit_report: @@ -188,23 +237,84 @@ html_report junit_report ============ -:Type: string +:Type: string (JSON) :Required: no -:Default Value: ``'StaticTypingSummary.xml'`` -:Possible Values: Any valid file name for mypy's JUnit XML report. -:Description: File name for the JUnit XML file. +:Default Value: + .. code-block:: json + + { "directory": "reports/typing", + "filename": "StaticTypingSummary.xml", + "fullpath": "reports/typing/StaticTypingSummary.xml" + } +:Possible Values: Any valid JSON string containing a JSON object with fields: + + :directory: Directory or sub-directory where the type checking report in JUnit XML format will be + saved. + :filename: Filename of the generated type checking report in JUnit XML format. |br| + Any valid file name for mypy's JUnit XML report. + :fullpath: The concatenation of both previous fields using the ``/`` separator. +:Description: Directory, filename and fullpath as JSON object where the type checking report in JUnit XML format + will be saved. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. +:Example: + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + UnitTesting: + uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5 + needs: + - ConfigParams + with: + ... + junit_report: ${{ needs.ConfigParams.outputs.statictyping_junit }} -.. _JOBTMPL/StaticTypeCheck/Input/html_artifact: +.. _JOBTMPL/StaticTypeCheck/Input/html_report: -html_artifact -============= +html_report +=========== + +:Type: string (JSON) +:Required: no +:Default Value: + .. code-block:: json + + { "directory": "reports/typing/html" + } +:Possible Values: Any valid JSON string containing a JSON object with fields: + + :directory: Directory or sub-directory where the type checking report in HTML format will be saved. +:Description: Directory as JSON object where the type checking report in HTML format will be saved. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. +:Example: + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + UnitTesting: + uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@r5 + needs: + - ConfigParams + with: + ... + html_report: ${{ needs.ConfigParams.outputs.statictyping_html }} + + +.. _JOBTMPL/StaticTypeCheck/Input/cobertura_artifact: + +cobertura_artifact +================== :Type: string :Required: no :Default Value: ``''`` :Possible Values: Any valid artifact name. -:Description: Name of the artifact containing the HTML report. +:Description: Name of the artifact containing the Cobertura XML report. .. _JOBTMPL/StaticTypeCheck/Input/junit_artifact: @@ -219,6 +329,18 @@ junit_artifact :Description: Name of the artifact containing the JUnit XML report. +.. _JOBTMPL/StaticTypeCheck/Input/html_artifact: + +html_artifact +============= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid artifact name. +:Description: Name of the artifact containing the HTML report. + + .. _JOBTMPL/StaticTypeCheck/Secrets: Secrets diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index 6b7db0c..34a6844 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -12,15 +12,19 @@ duplications within jobs. .. topic:: Features - * Concatenate :ref:`JOBTMPL/ExtractConfiguration/Input/package_namespace` and :ref:`JOBTMPL/ExtractConfiguration/Input/package_name` - to :ref:`JOBTMPL/ExtractConfiguration/Output/package_fullname` (with dot) and :ref:`JOBTMPL/ExtractConfiguration/Output/package_directory` - (with slash). - * Provide commands to prepare the source code directory structure suitable for mypy. - * Extract the unittest XML report file (pytest JUnit XML) as directory name, filename and full path from :file:`pyproject.toml`. + * Extract the unittest report file in pytest's JUnit XML format as directory name, filename and full path from + :file:`pyproject.toml`. * Extract the merged unittest XML report file as directory name, filename and full path from :file:`pyproject.toml`. - * Extract code coverage report HTML directory from :file:`pyproject.toml`. - * Extract code coverage XML report file as directory name, filename and full path from :file:`pyproject.toml`. - * Extract code coverage JSON report file as directory name, filename and full path from :file:`pyproject.toml`. + * Extract code coverage report in HTML format as directory from :file:`pyproject.toml`. + * Extract code coverage report file in Cobertura XML format as directory name, filename and full path from + :file:`pyproject.toml`. + * Extract code coverage report file in Coverage.py's JSON format as directory name, filename and full path from + :file:`pyproject.toml`. + * Extract static typing report file in Cobertura XML format as directory name, filename and full path from + :file:`pyproject.toml`. + * Extract static typing report file in JUnit XML format as directory name, filename and full path from + :file:`pyproject.toml`. + * Extract static typing report in HTML format as directory name from :file:`pyproject.toml`. .. topic:: Behavior @@ -29,9 +33,10 @@ duplications within jobs. 3. Compute the full package name and the package source directory. 4. Read :file:`pyproject.toml` and extract settings for: - * pytest - * Coverage.py - * pyEDAA.Reports + * :term:`Coverage.py` + * :term:`mypy` + * :term:`pyEDAA.Reports` + * :term:`pytest` .. topic:: Job Execution @@ -53,35 +58,24 @@ Instantiation ************* The following instantiation example creates a ``ConfigParams`` job derived from job template ``ExtractConfiguration`` -version ``@r5``. It only requires a :ref:`JOBTMPL/ExtractConfiguration/Input/package_name` parameter to extract unit -test (pytest) and code coverage (Coverage.py) settings. +version ``@r5``. It requires no special parameters to extract unit test (pytest) and code coverage (Coverage.py) +settings. .. code-block:: yaml - name: Pipeline - - on: - push: - workflow_dispatch: - jobs: ConfigParams: uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - with: - package_name: myPackage UnitTesting: uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 needs: - ConfigParams with: - unittest_report_xml_directory: ${{ needs.ConfigParams.outputs.unittest_report_xml_directory }} - unittest_report_xml_filename: ${{ needs.ConfigParams.outputs.unittest_report_xml_filename }} - coverage_report_xml_directory: ${{ needs.ConfigParams.outputs.coverage_report_xml_directory }} - coverage_report_xml_filename: ${{ needs.ConfigParams.outputs.coverage_report_xml_filename }} - coverage_report_json_directory: ${{ needs.ConfigParams.outputs.coverage_report_json_directory }} - coverage_report_json_filename: ${{ needs.ConfigParams.outputs.coverage_report_json_filename }} - coverage_report_html_directory: ${{ needs.ConfigParams.outputs.coverage_report_html_directory }} + unittest_report_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }} + coverage_report_xml: ${{ needs.ConfigParams.outputs.coverage_report_xml }} + coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }} + coverage_report_html: ${{ needs.ConfigParams.outputs.coverage_report_html }} .. seealso:: @@ -115,10 +109,6 @@ Parameter Summary +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/ExtractConfiguration/Input/python_version` | no | string | ``'3.13'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Input/package_namespace` | no | string | ``''`` | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Input/package_name` | yes | string | — — — — | -+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ | :ref:`JOBTMPL/ExtractConfiguration/Input/coverage_config` | no | string | ``'pyproject.toml'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ @@ -128,41 +118,25 @@ This job template needs no secrets. .. rubric:: Goto :ref:`output parameters ` -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| Result Name | Type | Description | -+=================================================================================+==========+===================================================================+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/package_fullname` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/package_directory` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/mypy_prepare_command` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_report_xml_directory` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_report_xml_filename` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_report_xml` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml_directory` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml_filename` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_html_directory` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_xml_directory` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_xml_filename` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_xml` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_json_directory` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_json_filename` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_json` | string | | -+---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| Result Name | Type | Description | ++=================================================================================+================+===================================================================+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_report_xml` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_html` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_xml` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_json` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/typing_report_cobertura` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/typing_report_junit` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/ExtractConfiguration/Output/typing_report_html` | string (JSON) | | ++---------------------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ .. _JOBTMPL/ExtractConfiguration/Inputs: @@ -180,101 +154,6 @@ Input Parameters .. include:: ../_python_version.rst -.. _JOBTMPL/ExtractConfiguration/Input/package_namespace: - -package_namespace -================= - -:Type: string -:Required: no -:Default Value: ``''`` -:Possible Values: Any valid Python namespace. -:Description: In case the package is a Python namespace package, the name of the library's or package's namespace - needs to be specified using this parameter. |br| - In case of a simple Python package, this parameter must be specified as an empty string (``''``), - which is the default. -:Example: - .. grid:: 2 - - .. grid-item:: - :columns: 5 - - .. rubric:: Example Instantiation - - .. code-block:: yaml - - name: Pipeline - - jobs: - ConfigParams: - uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - with: - package_namespace: myFramework - package_name: Extension - - .. grid-item:: - :columns: 4 - - .. rubric:: Example Directory Structure - - .. code-block:: - - 📂ProjectRoot/ - 📂myFramework/ - 📂Extension/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py - - -.. _JOBTMPL/ExtractConfiguration/Input/package_name: - -package_name -============ - -:Type: string -:Required: no -:Default Value: ``''`` -:Possible Values: Any valid Python package name. -:Description: In case of a simple Python package, this package's name is specified using this parameter. |br| - In case the package is a Python namespace package, the parameter - :ref:`JOBTMPL/ExtractConfiguration/Input/package_namespace` must be specified, too. -:Example: - .. grid:: 2 - - .. grid-item:: - :columns: 5 - - .. rubric:: Example Instantiation - - .. code-block:: yaml - - name: Pipeline - - jobs: - ConfigParams: - uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - with: - package_name: myPackage - - .. grid-item:: - :columns: 4 - - .. rubric:: Example Directory Structure - - .. code-block:: - - 📂ProjectRoot/ - 📂myFramework/ - 📦SubPackage/ - 🐍__init__.py - 🐍SubModuleA.py - 🐍__init__.py - 🐍ModuleB.py - - .. _JOBTMPL/ExtractConfiguration/Input/coverage_config: coverage_config @@ -296,12 +175,6 @@ coverage_config .. code-block:: toml - [tool.pytest] - junit_xml = "report/unit/UnittestReportSummary.xml" - - [tool.pyedaa-reports] - junit_xml = "report/unit/unittest.xml" - [tool.coverage.xml] output = "report/coverage/coverage.xml" @@ -310,7 +183,18 @@ coverage_config [tool.coverage.html] directory = "report/coverage/html" - title="Code Coverage of pyDummy" + title="Code Coverage of myPackage" + + [tool.mypy] + html_report = "report/typing/html" + junit_xml = "report/typing/StaticTypingSummary.xml" + cobertura_xml_report = "report/typing" + + [tool.pyedaa-reports] + junit_xml = "report/unit/unittest.xml" + + [tool.pytest] + junit_xml = "report/unit/UnittestReportSummary.xml" .. _JOBTMPL/ExtractConfiguration/Secrets: @@ -326,122 +210,87 @@ This job template needs no secrets. Outputs ******* -.. _JOBTMPL/ExtractConfiguration/Output/package_fullname: - -package_fullname -================ - -:Type: string -:Description: Returns the full package name composed from :ref:`JOBTMPL/ExtractConfiguration/Input/package_namespace` - and :ref:`JOBTMPL/ExtractConfiguration/Input/package_name`. -:Example: ``myFramework.Extension`` - - -.. _JOBTMPL/ExtractConfiguration/Output/package_directory: - -package_directory -================= - -:Type: string -:Description: Returns the full package path composed from :ref:`JOBTMPL/ExtractConfiguration/Input/package_namespace` - and :ref:`JOBTMPL/ExtractConfiguration/Input/package_name`. -:Example: ``myFramework/Extension`` - - -.. _JOBTMPL/ExtractConfiguration/Output/mypy_prepare_command: - -mypy_prepare_command -==================== - -:Type: string -:Description: Returns a preparation command for `mypy `__. |br| - In case the Python package is a namespace package, an :file:`__init__.py` must be created, otherwise - mypy has problems analyzing the namespace package. -:Example: ``touch myFramework/__init__.py`` - -.. _JOBTMPL/ExtractConfiguration/Output/unittest_report_xml_directory: - -unittest_report_xml_directory -============================= - -:Type: string -:Description: Returns the directory where the unittest XML report file (`pytest `__ JUnit XML) - will be created. |br| - This is the directory portion of :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_report_xml`. -:Example: :file:`reports/unit` -:pyproject.toml: - .. code-block:: toml - - [tool.pytest] - junit_xml = "report/unit/UnittestReportSummary.xml" - - -.. _JOBTMPL/ExtractConfiguration/Output/unittest_report_xml_filename: - -unittest_report_xml_filename -============================ - -:Type: string -:Description: Returns the filename of the unittest XML report file (`pytest `__ JUnit XML). |br| - This is the filename portion of :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_report_xml`. -:Example: :file:`UnittestReportSummary.xml` -:pyproject.toml: - .. code-block:: toml - - [tool.pytest] - junit_xml = "report/unit/UnittestReportSummary.xml" - - .. _JOBTMPL/ExtractConfiguration/Output/unittest_report_xml: unittest_report_xml =================== -:Type: string -:Description: Returns the path where the unittest XML report file (`pytest `__ JUnit XML) - will be created. |br| - This is the concatenation of :ref:`directory portion ` - and :ref:`filename portion `. -:Example: :file:`reports/unit/UnittestReportSummary.xml` -:pyproject.toml: +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory, the filename and the fullpath to the unit + test's report XML file created by :term:`pytest` in JUnit XML format. + + The JSON object contains these fields: + + :directory: Contains the directory where the unittest XML report file will be created. |br| + Example: :file:`reports/unit` + :filename: Contains the filename of the unittest XML report file. |br| + Example: :file:`UnittestReportSummary.xml` + :fullpath: Contains the path where the unittest XML report file will be created. |br| + This is the concatenation of both previous JSON fields. |br| + Example: :file:`reports/unit/UnittestReportSummary.xml` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`pytest`. + .. code-block:: toml [tool.pytest] junit_xml = "report/unit/UnittestReportSummary.xml" +:Example: + .. code-block:: json + { "directory": "reports/unit", + "filename": "UnittestReportSummary.xml", + "fullpath": "reports/unit/UnittestReportSummary.xml" + } +:Usage: + .. tab-set:: -.. _JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml_directory: + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam -unittest_merged_report_xml_directory -==================================== + .. code-block:: yaml -:Type: string -:Description: Returns the directory where the merged unittest XML report file - (`pyedaa-reports `__ JUnit XML) will be created. |br| - This is the directory portion of :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml`. -:Example: :file:`reports/unit` -:pyproject.toml: - .. code-block:: toml + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - [tool.pyedaa-reports] - junit_xml = "report/unit/unittest.xml" + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.unittest_report_xml }} + .. tab-item:: Assembling new JSON object + :sync: AssembleParam -.. _JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml_filename: + .. code-block:: yaml -unittest_merged_report_xml_filename -=================================== + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 -:Type: string -:Description: Returns the filename of the merged unittest XML report - (`pyedaa-reports `__ JUnit XML). |br| - This is the filename portion of :ref:`JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml`. -:Example: :file:`unittest.xml` -:pyproject.toml: - .. code-block:: toml + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.unittest_report_xml).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.unittest_report_xml).filename }}" + } - [tool.pyedaa-reports] - junit_xml = "report/unit/unittest.xml" + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.unittest_report_xml).fullpath }} .. _JOBTMPL/ExtractConfiguration/Output/unittest_merged_report_xml: @@ -449,67 +298,163 @@ unittest_merged_report_xml_filename unittest_merged_report_xml ========================== -:Type: string -:Description: Returns the path where the merged unittest XML report file (`pyedaa-reports `__ JUnit XML) - will be created. |br| - This is the concatenation of :ref:`directory portion ` - and :ref:`filename portion `. -:Example: :file:`report/unit/unittest.xml` -:pyproject.toml: +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory, the filename and the fullpath to the merged + unittest report file in JUnit XML format created by :term:`pyEDAA.Reports`. + + The JSON object contains these fields: + + :directory: Contains the directory where the merged unittest XML report file will be created. |br| + Example: :file:`reports/unit` + :filename: Contains the filename of the merged unittest XML report file. |br| + Example: :file:`unittest.xml` + :fullpath: Contains the path where the merged unittest XML report file will be created. |br| + This is the concatenation of both previous JSON fields. |br| + Example: :file:`reports/unit/unittest.xml` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`pyEDAA.Reports`. + .. code-block:: toml [tool.pyedaa-reports] junit_xml = "report/unit/unittest.xml" +:Example: + .. code-block:: json + + { "directory": "reports/unit", + "filename": "unittest.xml", + "fullpath": "reports/unit/unittest.xml" + } +:Usage: + .. tab-set:: + + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.unittest_merged_report_xml }} + + .. tab-item:: Assembling new JSON object + :sync: AssembleParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.unittest_merged_report_xml).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.unittest_merged_report_xml).filename }}" + } + + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.unittest_merged_report_xml).fullpath }} -.. _JOBTMPL/ExtractConfiguration/Output/coverage_report_html_directory: +.. _JOBTMPL/ExtractConfiguration/Output/coverage_report_html: -coverage_report_html_directory -============================== +coverage_report_html +==================== + +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory and the full path, where the code coverage + HTML report will be generated by :term:`Coverage.py`. + + The JSON object contains these fields: + + :directory: Contains the directory where the code coverage report in HTML format will be created. |br| + Example: :file:`report/coverage/html` + :fullpath: Contains the path where the code coverage report in HTML format will be created. |br| + This is the same as the previous JSON field. |br| + Example: :file:`report/coverage/html` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`Coverage.py`. -:Type: string -:Description: Returns the directory where the code coverage HTML report (`Coverage.py `__) - will be generated. -:Example: :file:`report/coverage/html` -:pyproject.toml: .. code-block:: toml [tool.coverage.html] directory = "report/coverage/html" title="Code Coverage of pyDummy" +:Example: + .. code-block:: json + { "directory": "report/coverage/html", + "fullpath": "report/coverage/html" + } +:Usage: + .. tab-set:: -.. _JOBTMPL/ExtractConfiguration/Output/coverage_report_xml_directory: + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam -coverage_report_xml_directory -============================= + .. code-block:: yaml -:Type: string -:Description: Returns the directory where the code coverage XML report file (`Coverage.py `__) - will be created. |br| - This is the directory portion of :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_xml`. -:Example: :file:`reports/coverage` -:pyproject.toml: - .. code-block:: toml + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - [tool.coverage.xml] - output = "report/coverage/coverage.xml" + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.coverage_report_html }} + .. tab-item:: Assembling new JSON object + :sync: AssembleParam -.. _JOBTMPL/ExtractConfiguration/Output/coverage_report_xml_filename: + .. code-block:: yaml -coverage_report_xml_filename -============================ + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 -:Type: string -:Description: Returns the filename of the code coverage XML report file (`Coverage.py `__). |br| - This is the filename portion of :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_xml`. -:Example: :file:`coverage.xml` -:pyproject.toml: - .. code-block:: toml + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.coverage_report_html).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.coverage_report_html).filename }}" + } - [tool.coverage.xml] - output = "report/coverage/coverage.xml" + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.coverage_report_html).fullpath }} .. _JOBTMPL/ExtractConfiguration/Output/coverage_report_xml: @@ -517,50 +462,82 @@ coverage_report_xml_filename coverage_report_xml =================== -:Type: string -:Description: Returns the path where the code coverage XML report file (`Coverage.py `__) - will be created. |br| - This is the concatenation of :ref:`directory portion ` - and :ref:`filename portion `. -:Example: :file:`report/coverage/coverage.xml` -:pyproject.toml: +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory, the filename and the fullpath to the code + coverage XML report file in Cobertura XML format created by :term:`Coverage.py`. + + The JSON object contains these fields: + + :directory: Contains the directory where the code coverage XML report file will be created. |br| + Example: :file:`reports/unit` + :filename: Contains the filename of the code coverage XML report file. |br| + Example: :file:`unittest.xml` + :fullpath: Contains the path where the code coverage XML report file will be created. |br| + This is the concatenation of both previous JSON fields. |br| + Example: :file:`reports/unit/unittest.xml` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`Coverage.py`. + .. code-block:: toml [tool.coverage.xml] output = "report/coverage/coverage.xml" +:Example: + .. code-block:: json + { "directory": "reports/coverage", + "filename": "coverage.xml", + "fullpath": "reports/coverage/coverage.xml" + } +:Usage: + .. tab-set:: -.. _JOBTMPL/ExtractConfiguration/Output/coverage_report_json_directory: + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam -coverage_report_json_directory -============================== + .. code-block:: yaml -:Type: string -:Description: Returns the directory where the code coverage JSON report file (`Coverage.py `__) - will be created. |br| - This is the directory portion of :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_json`. -:Example: :file:`reports/coverage` -:pyproject.toml: - .. code-block:: toml + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - [tool.coverage.json] - output = "report/coverage/coverage.json" + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.coverage_report_xml }} + .. tab-item:: Assembling new JSON object + :sync: AssembleParam -.. _JOBTMPL/ExtractConfiguration/Output/coverage_report_json_filename: + .. code-block:: yaml -coverage_report_json_filename -============================= + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 -:Type: string -:Description: Returns the filename of the code coverage JSON report file (`Coverage.py `__). |br| - This is the filename portion of :ref:`JOBTMPL/ExtractConfiguration/Output/coverage_report_json`. -:Example: :file:`coverage.json` -:pyproject.toml: - .. code-block:: toml + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.coverage_report_xml).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.coverage_report_xml).filename }}" + } - [tool.coverage.json] - output = "report/coverage/coverage.json" + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.coverage_report_xml).fullpath }} .. _JOBTMPL/ExtractConfiguration/Output/coverage_report_json: @@ -568,17 +545,328 @@ coverage_report_json_filename coverage_report_json ==================== -:Type: string -:Description: Returns the path where the code coverage JSON report file (`Coverage.py `__) - will be created. |br| - This is the concatenation of :ref:`directory portion ` - and :ref:`filename portion `. -:Example: :file:`report/coverage/coverage.json` -:pyproject.toml: +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory, the filename and the fullpath to the code + coverage JSON report file created by :term:`Coverage.py`. + + The JSON object contains these fields: + + :directory: Contains the directory where the code coverage JSON report file will be created. |br| + Example: :file:`reports/unit` + :filename: Contains the filename of the code coverage JSON report file. |br| + Example: :file:`unittest.json` + :fullpath: Contains the path where the code coverage JSON report file will be created. |br| + This is the concatenation of both previous JSON fields. |br| + Example: :file:`reports/unit/unittest.json` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`Coverage.py`. + .. code-block:: toml [tool.coverage.json] output = "report/coverage/coverage.json" +:Example: + .. code-block:: json + + { "directory": "reports/coverage", + "filename": "coverage.json", + "fullpath": "reports/coverage/coverage.json" + } +:Usage: + .. tab-set:: + + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.coverage_report_json }} + + .. tab-item:: Assembling new JSON object + :sync: AssembleParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.coverage_report_json).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.coverage_report_json).filename }}" + } + + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.coverage_report_json).fullpath }} + + +.. _JOBTMPL/ExtractConfiguration/Output/typing_report_cobertura: + +typing_report_cobertura +======================= + +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory, the filename and the fullpath to the static + type checking report file in Cobertura format created by :term:`mypy`. + + The JSON object contains these fields: + + :directory: Contains the directory where the type checking XML report file will be created. |br| + Example: :file:`reports/typing` + :filename: Contains the filename of the type checking XML report file. |br| + Example: :file:`cobertura.xml` + :fullpath: Contains the path where the type checking XML report file will be created. |br| + This is the concatenation of both previous JSON fields. |br| + Example: :file:`reports/typing/cobertura.xml` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`mypy`. + + .. code-block:: toml + + [tool.mypy] + cobertura_xml_report = "report/typing" +:Example: + .. code-block:: json + + { "directory": "reports/typing", + "filename": "cobertura.xml", + "fullpath": "reports/typing/cobertura.xml" + } +:Usage: + .. tab-set:: + + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.typing_report_cobertura }} + + .. tab-item:: Assembling new JSON object + :sync: AssembleParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.typing_report_cobertura).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.typing_report_cobertura).filename }}" + } + + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.typing_report_cobertura).fullpath }} + + +.. _JOBTMPL/ExtractConfiguration/Output/typing_report_junit: + +typing_report_junit +=================== + +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory, the filename and the fullpath to the static + type checking report file in JUnit XML format created by :term:`mypy`. + + The JSON object contains these fields: + + :directory: Contains the directory where the static typing JUnit XML report file will be created. |br| + Example: :file:`reports/typing` + :filename: Contains the filename of the static typing JUnit XML report file. |br| + Example: :file:`StaticTypingSummary.xml` + :fullpath: Contains the path where the cstatic typing JUnit XML report file will be created. |br| + This is the concatenation of both previous JSON fields. |br| + Example: :file:`reports/typing/StaticTypingSummary.xml` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`mypy`. + + .. code-block:: toml + + [tool.mypy] + junit_xml = "report/typing/StaticTypingSummary.xml" +:Example: + .. code-block:: json + + { "directory": "reports/typing", + "filename": "StaticTypingSummary.xml", + "fullpath": "reports/typing/StaticTypingSummary.xml" + } +:Usage: + .. tab-set:: + + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.typing_report_junit }} + + .. tab-item:: Assembling new JSON object + :sync: AssembleParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.typing_report_junit).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.typing_report_junit).filename }}" + } + + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.typing_report_junit).fullpath }} + + +.. _JOBTMPL/ExtractConfiguration/Output/typing_report_html: + +typing_report_html +================== + +:Type: string (JSON) +:Description: Returns a string in JSON format containing the directory, the filename and the fullpath to the static + type checking report in HTML format created by :term:`mypy`. + + The JSON object contains these fields: + + :directory: Contains the directory where the static typing HTML report will be created. |br| + Example: :file:`reports/typing/html` + :fullpath: Contains the path where the static typing HTML report will be created. |br| + This is the same as the previous JSON field. |br| + Example: :file:`reports/typing/html` +:pyproject.toml: Matching :file:`pyproject.toml` configuration for tool :term:`mypy`. + + .. code-block:: toml + + [tool.mypy] + html_report = "report/typing/html" +:Example: + .. code-block:: json + + { "directory": "reports/typing/html", + "fullpath": "reports/typing/html" + } +:Usage: + .. tab-set:: + + .. tab-item:: Forwarding complete JSON object + :sync: ForwardParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: ${{ needs.ConfigParams.outputs.typing_report_html }} + + .. tab-item:: Assembling new JSON object + :sync: AssembleParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + report: >- + { "dir": "${{ fromJson(needs.ConfigParams.outputs.typing_report_html).directory }}", + "file": "${{ fromJson(needs.ConfigParams.outputs.typing_report_html).filename }}" + } + + .. tab-item:: Using single field from JSON object + :sync: SingleFieldFromParam + + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + OtherJob: + uses: some/path/to/a/template@r5 + needs: + - ConfigParams + with: + fullpath: ${{ fromJson(needs.ConfigParams.outputs.typing_report_html).fullpath }} .. _JOBTMPL/ExtractConfiguration/Optimizations: diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index 46d8033..232a05b 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -208,17 +208,21 @@ This job template needs no secrets. .. rubric:: Goto :ref:`output parameters ` -+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| Result Name | Type | Description | -+=====================================================================+==========+===================================================================+ -| :ref:`JOBTMPL/Parameters/Output/python_version` | string | | -+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Output/python_jobs` | string | | -+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Output/artifact_names` | string | | -+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/Parameters/Output/params` | string | **deprecated** | -+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ ++---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| Result Name | Type | Description | ++=====================================================================+================+===================================================================+ +| :ref:`JOBTMPL/Parameters/Output/python_version` | string | | ++---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Output/package_fullname` | string | | ++---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Output/package_directory` | string | | ++---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Output/artifact_basename` | string | | ++---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Output/artifact_names` | string (JSON) | | ++---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Parameters/Output/python_jobs` | string (JSON) | | ++---------------------------------------------------------------------+----------------+-------------------------------------------------------------------+ .. _JOBTMPL/Parameters/Inputs: @@ -591,6 +595,87 @@ python_version python_version: ${{ needs.Params.outputs.python_version }} +.. _JOBTMPL/Parameters/Output/package_fullname: + +package_fullname +================ + +:Type: string +:Description: Returns the full package name composed from :ref:`JOBTMPL/Parameters/Input/package_namespace` + and :ref:`JOBTMPL/Parameters/Input/package_name`. +:Example: ``myFramework.Extension`` + + +.. _JOBTMPL/Parameters/Output/package_directory: + +package_directory +================= + +:Type: string +:Description: Returns the full package path composed from :ref:`JOBTMPL/Parameters/Input/package_namespace` + and :ref:`JOBTMPL/Parameters/Input/package_name`. +:Example: ``myFramework/Extension`` + + +.. _JOBTMPL/Parameters/Output/artifact_basename: + +artifact_basename +================= + +:Type: string +:Description: Returns the basename (prefix) of all :ref:`artifact names ` |br|. + The basename is either :ref:`JOBTMPL/Parameters/Input/name` if set, otherwise its + :ref:`JOBTMPL/Parameters/Output/package_fullname`. +:Example: ``myFramework.Extension`` + + +.. _JOBTMPL/Parameters/Output/artifact_names: + +artifact_names +============== + +:Type: string (JSON) +:Description: Returns a JSON dictionary of artifact names sharing a common prefix (see :ref:`JOBTMPL/Parameters/Input/name`). |br| + As artifacts are handed from jo to job, a consistent naming scheme is advised to avoid duplications + and naming artifacts by hand. This technique solves again the problem of global variables in GitHub + Action YAMl files and the need for assigning the same value (here artifact name) to multiple jobs + templates. + + The supported artifacts are: + + :unittesting_xml: UnitTesting XML summary report + :unittesting_html: UnitTesting HTML summary report + :perftesting_xml: PerformanceTesting XML summary report + :benchtesting_xml: Benchmarking XML summary report + :apptesting_xml: ApplicationTesting XML summary report + :codecoverage_sqlite: Code Coverage internal database (SQLite) + :codecoverage_xml: Code Coverage Cobertura XML report + :codecoverage_json: Code Coverage Coverage.py JSON report + :codecoverage_html: Code Coverage HTML report + :statictyping_cobertura: Static Type Checking Cobertura XML report + :statictyping_junit: Static Type Checking JUnit XML report + :statictyping_html: Static Type Checking HTML report + :package_all: Packaged Python project (multiple formats) + :documentation_html: Documentation in HTML format + :documentation_latex: Documentation in LaTeX format + :documentation_pdf: Documentation in PDF format +:Example: + .. code-block:: yaml + + jobs: + Params: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 + with: + name: pyTooling + + Coverage: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 + needs: + - Params + with: + unittest_xml_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }} + + .. _JOBTMPL/Parameters/Output/python_jobs: python_jobs @@ -600,14 +685,14 @@ python_jobs :Description: Returns a JSON array of job descriptions, wherein each job description is a dictionary providing the following key-value pairs: - * ``sysicon`` - icon to display - * ``system`` - name of the system - * ``runs-on`` - virtual machine image and base operating system - * ``runtime`` - name of the runtime environment if not running natively on the VM image - * ``shell`` - name of the shell - * ``pyicon`` - icon for CPython or pypy - * ``python`` - Python version - * ``envname`` - full name of the selected environment + :sysicon: icon to display + :system: name of the system + :runs-on: virtual machine image and base operating system + :runtime: name of the runtime environment if not running natively on the VM image + :shell: name of the shell + :pyicon: icon for CPython or pypy + :python: Python version + :envname: full name of the selected environment :Example: .. code-block:: yaml @@ -683,67 +768,6 @@ python_jobs {"sysicon": "🪟🟨", "system": "msys2", "runs-on": "windows-2025", "runtime": "UCRT64", "shell": "msys2 {0}", "pyicon": "🟢", "python": "3.12", "envname": "Windows+MSYS2 (x86-64) - UCRT64" } ] -.. _JOBTMPL/Parameters/Output/artifact_names: - -artifact_names -============== - -:Type: string (JSON) -:Description: Returns a JSON dictionary of artifact names sharing a common prefix (see :ref:`JOBTMPL/Parameters/Input/name`). |br| - As artifacts are handed from jo to job, a consistent naming scheme is advised to avoid duplications - and naming artifacts by hand. This technique solves again the problem of global variables in GitHub - Action YAMl files and the need for assigning the same value (here artifact name) to multiple jobs - templates. - - The supported artifacts are: - - * ``unittesting_xml`` - UnitTesting XML summary report - * ``unittesting_html`` - UnitTesting HTML summary report - * ``perftesting_xml`` - PerformanceTesting XML summary report - * ``benchtesting_xml`` - Benchmarking XML summary report - * ``apptesting_xml`` - ApplicationTesting XML summary report - * ``codecoverage_sqlite`` - Code Coverage internal database (SQLite) - * ``codecoverage_xml`` - Code Coverage XML report - * ``codecoverage_json`` - Code Coverage JSON report - * ``codecoverage_html`` - Code Coverage HTML report - * ``statictyping_html`` - Static Type Checking HTML report - * ``package_all`` - Packaged Python project (multiple formats) - * ``documentation_html`` - Documentation in HTML format - * ``documentation_latex`` - Documentation in LaTeX format - * ``documentation_pdf`` - Documentation in PDF format -:Example: - .. code-block:: yaml - - jobs: - Params: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 - with: - name: pyTooling - - Coverage: - uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 - needs: - - Params - with: - unittest_xml_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }} - - -.. _JOBTMPL/Parameters/Output/params: - -params -====== - -.. attention:: ``params`` is deprecated. - -:Type: string (JSON) -:Description: Returns a JSON dictionary of artifact names. |br| - Use :ref:`JOBTMPL/Parameters/Output/artifact_names` as a more powerful replacement. -:Replacements: * ``params['unittesting']`` |rarr| ``artifact_names['unittesting_xml']`` - * ``params['coverage']`` |rarr| ``artifact_names['codecoverage_xml']`` - * ``params['typing']`` |rarr| ``artifact_names['statictyping_html']`` - * ``params['package']`` |rarr| ``artifact_names['package_all']`` - * ``params['doc']`` |rarr| ``artifact_names['documentation_html']`` - .. _JOBTMPL/Parameters/Optimizations: diff --git a/doc/JobTemplate/Testing/UnitTesting.rst b/doc/JobTemplate/Testing/UnitTesting.rst index f63c123..a49a910 100644 --- a/doc/JobTemplate/Testing/UnitTesting.rst +++ b/doc/JobTemplate/Testing/UnitTesting.rst @@ -77,17 +77,9 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se .. code-block:: yaml - name: Pipeline - - on: - push: - workflow_dispatch: - jobs: ConfigParams: uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 - with: - package_name: myPackage UnitTestingParams: uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 @@ -100,26 +92,11 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se - ConfigParams - UnitTestingParams with: - jobs: ${{ needs.UnitTestingParams.outputs.python_jobs }} - requirements: "-r tests/unit/requirements.txt" - unittest_report_xml_directory: ${{ needs.ConfigParams.outputs.unittest_report_xml_directory }} - unittest_report_xml_filename: ${{ needs.ConfigParams.outputs.unittest_report_xml_filename }} - unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }} - coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }} - -.. code-block:: yaml - - jobs: - Params: - # ... - - UnitTesting: - uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 - needs: - - Params - with: - jobs: ${{ needs.Params.outputs.python_jobs }} - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting }} + jobs: ${{ needs.UnitTestingParams.outputs.python_jobs }} + requirements: '-r tests/unit/requirements.txt' + unittest_report_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }} + unittest_xml_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).unittesting_xml }} + coverage_sqlite_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).codecoverage_sqlite }} .. seealso:: @@ -138,67 +115,69 @@ the :ref:`JOBTMPL/ExtractConfiguration` job template is used to extract these se Parameter Summary ***************** +.. # |unittest_report_xml| code-block:: json + + { "directory": "report/unit", + "filename": "TestReportSummary.xml", + "fullpath": "report/unit/TestReportSummary.xml" + } + + .. rubric:: Goto :ref:`input parameters ` -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| Parameter Name | Required | Type | Default | -+=========================================================================+==========+==========+===================================================================+ -| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml_directory` | no | string | ``'report/unit'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml_filename` | no | string | ``'TestReportSummary.xml'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml_directory` | no | string | ``'report/coverage'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml_filename` | no | string | ``'coverage.xml'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json_directory` | no | string | ``'report/coverage'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json_filename` | no | string | ``'coverage.json'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html_directory` | no | string | ``'report/coverage/html'`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` | -+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=========================================================================+==========+==========+===================================================================================================================================+ +| :ref:`JOBTMPL/UnitTesting/Input/jobs` | yes | string | — — — — | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/apt` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/brew` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/pacboy` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/requirements` | no | string | ``'-r tests/requirements.txt'`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/mingw_requirements` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/macos_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/macos_arm_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/ubuntu_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/mingw64_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/ucrt64_before_script` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/root_directory` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/tests_directory` | no | string | ``'tests'`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_directory` | no | string | ``'unit'`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_report_xml` | no | string | :jsoncode:`{"directory": "report/unit", "filename": "TestReportSummary.xml", "fullpath": "report/unit/TestReportSummary.xml"}` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_config` | no | string | ``'pyproject.toml'`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_xml` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.xml", "fullpath": "report/coverage/coverage.xml"}` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_json` | no | string | :jsoncode:`{"directory": "report/coverage", "filename": "coverage.json", "fullpath": "report/coverage/coverage.json"}` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_report_html` | no | string | :jsoncode:`{"directory": "report/coverage"}` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_xml_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/unittest_html_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_sqlite_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_xml_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_json_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`JOBTMPL/UnitTesting/Input/coverage_html_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-----------------------------------------------------------------------------------------------------------------------------------+ .. rubric:: Goto :ref:`secrets ` @@ -224,14 +203,14 @@ jobs :Default Value: — — — — :Possible Values: A JSON string with an array of dictionaries with the following key-value pairs: - * ``sysicon`` - icon to display - * ``system`` - name of the system - * ``runs-on`` - virtual machine image and base operating system - * ``runtime`` - name of the runtime environment if not running natively on the VM image - * ``shell`` - name of the shell - * ``pyicon`` - icon for CPython or pypy - * ``python`` - Python version - * ``envname`` - full name of the selected environment + :sysicon: icon to display + :system: name of the system + :runs-on: virtual machine image and base operating system + :runtime: name of the runtime environment if not running natively on the VM image + :shell: name of the shell + :pyicon: icon for CPython or pypy + :python: Python version + :envname: full name of the selected environment :Description: A JSON encoded job matrix to run multiple Python job variations. @@ -506,30 +485,43 @@ unittest_directory :Description: Path to the directory containing unit tests (relative from :ref:`JOBTMPL/UnitTesting/Input/tests_directory`). -.. _JOBTMPL/UnitTesting/Input/unittest_report_xml_directory: +.. _JOBTMPL/UnitTesting/Input/unittest_report_xml: -unittest_report_xml_directory -============================= +unittest_report_xml +=================== -:Type: string +:Type: string (JSON) :Required: no -:Default Value: ``'report/unit'`` -:Possible Values: Any valid directory or sub-directory. -:Description: Directory or sub-directory where the unittest summary report in XML format will be saved. |br| - This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. +:Default Value: + .. code-block:: json + { "directory": "reports/unit", + "filename": "UnittestReportSummary.xml", + "fullpath": "reports/unit/UnittestReportSummary.xml" + } +:Possible Values: Any valid JSON string containing a JSON object with fields: -.. _JOBTMPL/UnitTesting/Input/unittest_report_xml_filename: + :directory: Directory or sub-directory where the unittest summary report in XML format will be saved. + :filename: Filename of the generated JUnit XML report. |br| + Any valid filename accepted by ``pytest ... --junitxml=${unittest_report_xml}``. + :fullpath: The concatenation of both previous fields using the ``/`` separator. +:Description: Directory, filename and fullpath as JSON object where the unittest summary report in XML format will + be saved. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. +:Example: + .. code-block:: yaml -unittest_report_xml_filename -============================ + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 -:Type: string -:Required: no -:Default Value: ``'TestReportSummary.xml'`` -:Possible Values: Any valid filename accepted by ``pytest ... --junitxml=${unittest_report_xml_filename}``. -:Description: Filename of the generated JUnit XML report. |br| - This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. + UnitTesting: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 + needs: + - ConfigParams + with: + ... + unittest_report_xml: ${{ needs.ConfigParams.outputs.unittest_report_xml }} .. _JOBTMPL/UnitTesting/Input/coverage_config: @@ -543,69 +535,117 @@ coverage_config :Possible Values: TBD -.. _JOBTMPL/UnitTesting/Input/coverage_report_xml_directory: +.. _JOBTMPL/UnitTesting/Input/coverage_report_xml: -coverage_report_xml_directory -============================= +coverage_report_xml +=================== -:Type: string +:Type: string (JSON) :Required: no -:Default Value: ``'report/coverage'`` -:Possible Values: Any valid directory or sub-directory. -:Description: Directory or sub-directory where the code covergae report in XML format will be saved. |br| - This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. +:Default Value: + .. code-block:: json + + { "directory": "reports/coverage", + "filename": "coverage.xml", + "fullpath": "reports/coverage/coverage.xml" + } +:Possible Values: Any valid JSON string containing a JSON object with fields: + + :directory: Directory or sub-directory where the code coverage report in Cobertura XML format will be + saved. + :filename: Filename of the generated Cobertura XML report. |br| + Any valid XML filename. + :fullpath: The concatenation of both previous fields using the ``/`` separator. +:Description: Directory, filename and fullpath as JSON object where the code coverage report in Cobertura XML format + will be saved. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. +:Example: + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + UnitTesting: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 + needs: + - ConfigParams + with: + ... + coverage_report_xml: ${{ needs.ConfigParams.outputs.coverage_report_xml }} -.. _JOBTMPL/UnitTesting/Input/coverage_report_xml_filename: +.. _JOBTMPL/UnitTesting/Input/coverage_report_json: -coverage_report_xml_filename -============================ +coverage_report_json +==================== -:Type: string +:Type: string (JSON) :Required: no -:Default Value: ``'coverage.xml'`` -:Possible Values: Any valid XML filename. -:Description: Filename of the generated code coverage report in Cobertura format. |br| - This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. +:Default Value: + .. code-block:: json + + { "directory": "reports/coverage", + "filename": "coverage.json", + "fullpath": "reports/coverage/coverage.json" + } +:Possible Values: Any valid JSON string containing a JSON object with fields: + + :directory: Directory or sub-directory where the code coverage report in Coverage.py's JSON format + will be saved. + :filename: Filename of the generated Coverage.py JSON report. |br| + Any valid JSON filename. + :fullpath: The concatenation of both previous fields using the ``/`` separator. +:Description: Directory, filename and fullpath as JSON object where the code coverage report in Coverage.py's JSON + format will be saved. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. +:Example: + .. code-block:: yaml + + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + + UnitTesting: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 + needs: + - ConfigParams + with: + ... + coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }} -.. _JOBTMPL/UnitTesting/Input/coverage_report_json_directory: +.. _JOBTMPL/UnitTesting/Input/coverage_report_html: -coverage_report_json_directory -============================== +coverage_report_html +==================== -:Type: string +:Type: string (JSON) :Required: no -:Default Value: ``'report/coverage'`` -:Possible Values: Any valid directory or sub-directory. -:Description: Directory or sub-directory where the code covergae report in JSON format will be saved. |br| - This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. +:Default Value: + .. code-block:: json + { "directory": "reports/coverage/html" + } +:Possible Values: Any valid JSON string containing a JSON object with fields: -.. _JOBTMPL/UnitTesting/Input/coverage_report_json_filename: + :directory: Directory or sub-directory where the code coverage report in HTML format will be saved. +:Description: Directory as JSON object where the code coverage report in HTML format will be saved. |br| + This path is configured in :file:`pyproject.toml` and can be extracted by + :ref:`JOBTMPL/ExtractConfiguration`. +:Example: + .. code-block:: yaml -coverage_report_json_filename -============================= + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 -:Type: string -:Required: no -:Default Value: ``'coverage.json'`` -:Possible Values: Any valid JSON filename. -:Description: Filename of the generated code coverage report in Coverage.py JSON format. |br| - This filename is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. - - -.. _JOBTMPL/UnitTesting/Input/coverage_report_html_directory: - -coverage_report_html_directory -============================== - -:Type: string -:Required: no -:Default Value: ``'report/coverage/html'`` -:Possible Values: Any valid directory or sub-directory. -:Description: Directory or sub-directory where the code covergae report in HTML format will be saved. |br| - This path is configured in :file:`pyproject.toml` and can be extracted by :ref:`JOBTMPL/ExtractConfiguration`. + UnitTesting: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 + needs: + - ConfigParams + with: + ... + coverage_report_html: ${{ needs.ConfigParams.outputs.coverage_report_html }} .. _JOBTMPL/UnitTesting/Input/unittest_xml_artifact: diff --git a/doc/_static/css/override.css b/doc/_static/css/override.css index f5a275c..b2ce7f4 100644 --- a/doc/_static/css/override.css +++ b/doc/_static/css/override.css @@ -1,24 +1,8 @@ -/* theme overrides */ -.rst-content h1, -.rst-content h2 { - margin-top: 24px; - margin-bottom: 6px; - text-decoration: underline; -} +/* + Theme overrides for ReadTheDocs Theme by Patrick Lehmann +*/ -.rst-content h3, -.rst-content h4, -.rst-content h5, -.rst-content h6 { - margin-top: 12px; - margin-bottom: 6px; -} - -.rst-content p { - margin-bottom: 6px -} - -/* general overrides */ +/* General overrides */ html { font-size: 15px; } @@ -33,10 +17,20 @@ footer p { font-size: 95% } -section > p, -.section p, -.simple li { - text-align: justify +/* Headline */ +.rst-content h1, +.rst-content h2 { + margin-top: 24px; + margin-bottom: 6px; + text-decoration: underline; +} + +.rst-content h3, +.rst-content h4, +.rst-content h5, +.rst-content h6 { + margin-top: 12px; + margin-bottom: 6px; } .rst-content .topic-title { @@ -54,6 +48,31 @@ section > p, margin-bottom: 16px; } +/* Paragraphs */ +.rst-content p { + margin-bottom: 6px +} + +section > p, +.section p, +.simple li { + text-align: justify +} + +/* Field lists*/ +/* last paragraph in a field list*/ +dl.field-list > dd > p:last-of-type { + margin-bottom: 6px /* 12px */ +} +/* Nested field lists */ +dl.field-list > dd > dl.field-list.simple { + margin-bottom: 0px /* 24px */ +} +/* code-block within field list */ +dl.field-list > dd > div:has(div.highlight) { + margin-bottom: 0px /* 24px */ +} + /* wyrm overrides */ .wy-menu-vertical header, .wy-menu-vertical p.caption { @@ -66,8 +85,6 @@ section > p, .wy-side-nav-search { margin-bottom: 0 /* .809em */; background-color: #333333 /* #2980b9 */; - /* BTD: */ - /*color: #fcfcfc*/ } .wy-side-nav-search input[type=text] { @@ -75,15 +92,11 @@ section > p, } .wy-side-nav-search .wy-dropdown > a, .wy-side-nav-search > a { - /* BTD: */ - /*color: #fcfcfc;*/ margin-bottom: 0.404em /* .809em */; } .wy-side-nav-search > div.version { margin: 0 0 6px 0; - /* BTD: */ - /*margin-top: -.4045em;*/ } .wy-nav .wy-menu-vertical a:hover { @@ -98,7 +111,7 @@ section > p, background: #333333 /* #2980b9 */; } -/* Sphinx Design */ +/* Theme overrides for Sphinx Design by Patrick Lehmann */ .sd-tab-set { margin: 0 } diff --git a/doc/conf.py b/doc/conf.py index 9c6b841..0ef5c4f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,7 +1,7 @@ # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -from sys import path as sys_path +from sys import path as sys_path from os.path import abspath from pathlib import Path @@ -35,6 +35,7 @@ sys_path.insert(0, abspath(f"../{directoryName}")) packageInformationFile = Path(f"../{directoryName}/__init__.py") versionInformation = extractVersionInformation(packageInformationFile) +project = f"{githubNamespace}/{githubProject}" author = versionInformation.Author copyright = versionInformation.Copyright version = ".".join(versionInformation.Version.split(".")[:2]) # e.g. 2.3 The short X.Y version. @@ -80,6 +81,7 @@ except Exception as ex: # ============================================================================== # Options for HTML output # ============================================================================== +html_title = f"{githubNamespace}/{githubProject} v{versionInformation.Version}" html_theme = "sphinx_rtd_theme" html_theme_options = { "logo_only": True, @@ -190,7 +192,8 @@ extensions = [ # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { - "python": ("https://docs.python.org/3", None), + "python": ("https://docs.python.org/3", None), + "pyEDAARpt": ("https://edaa-org.github.io/pyEDAA.Reports", None), } @@ -299,7 +302,7 @@ report_doccov_packages = { # ============================================================================== autoapi_modules = { f"{pythonProject}": { - "template": "package", + "template": "module", "output": pythonProject, "override": True } diff --git a/doc/index.rst b/doc/index.rst index 08291db..f23b827 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -300,7 +300,7 @@ License :caption: pyDummy Example :hidden: - myPackage/myPackage + Python Class Reference unittests/index coverage/index CodeCoverage @@ -319,4 +319,5 @@ License Doc-License Glossary genindex + Python Module Index TODO diff --git a/doc/prolog.inc b/doc/prolog.inc index 75463a8..79ce733 100644 --- a/doc/prolog.inc +++ b/doc/prolog.inc @@ -54,6 +54,14 @@ .. role:: addition :class: colorgreen +.. role:: bashcode(code) + :language: bash + :class: highlight + .. role:: pycode(code) :language: python :class: highlight + +.. role:: jsoncode(code) + :language: json + :class: highlight