diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 8380fec..0872132 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -258,7 +258,7 @@ Parameter Summary | :ref:`JOBTMPL/CompletePipeline/Input/cleanup` | no | string | ``'true'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------+ -.. rubric:: Goto Goto :ref:`secrets ` +.. rubric:: Goto :ref:`secrets ` +-----------------------------------------------------------+----------+----------+--------------+ | Token Name | Required | Type | Default | @@ -270,7 +270,7 @@ Parameter Summary | :ref:`JOBTMPL/CompletePipeline/Secret/CODACY_TOKEN` | no | string | — — — — | +-----------------------------------------------------------+----------+----------+--------------+ -.. rubric:: Goto Goto :ref:`output parameters ` +.. rubric:: Goto :ref:`output parameters ` This job template has no output parameters. diff --git a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst index 375c238..e2cd7df 100644 --- a/doc/JobTemplate/Documentation/LaTeXDocumentation.rst +++ b/doc/JobTemplate/Documentation/LaTeXDocumentation.rst @@ -3,20 +3,181 @@ LatexDocumentation ################## -.. todo:: LatexDocumentation:Needs documentation. +The ``LatexDocumentation`` job template ................ -**Behavior:** +.. topic:: Features -.. todo:: LatexDocumentation:Behavior needs documentation. + * Translate a LaTeX document to PDF. -**Dependencies:** +.. topic:: Behavior: -.. todo:: LatexDocumentation:Dependencies needs documentation. + .. todo:: LatexDocumentation:Behavior needs documentation. + +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-LatexDocumentation.png + :width: 600px + +.. topic:: Dependencies + + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * :gh:`addnab/docker-run-action` + + * :dockerhub:`pytooling/miktex:sphinx` + + +.. _JOBTMPL/LatexDocumentation/Instantiation: Instantiation ************* -Simple Example +The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only +requires a `name` parameter to create the artifact names. + +.. code-block:: yaml + + name: Pipeline + + on: + push: + workflow_dispatch: + + jobs: + UnitTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 + with: + package_name: myPackage + + Documentation: + uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5 + needs: + - UnitTestingParams + with: + python_version: ${{ needs.UnitTestingParams.outputs.python_version }} + html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }} + latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }} + + PDFDocumentation: + uses: pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml@r5 + needs: + - UnitTestingParams + - Documentation + with: + document: pyEDAA.ProjectModel + latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }} + pdf_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }} + + +.. seealso:: + + :ref:`JOBTMPL/TagReleaseCommit` + ``LatexDocumentation`` is usualy + +.. _JOBTMPL/LatexDocumentation/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=====================================================================+==========+==========+===================================================================+ +| :ref:`JOBTMPL/LatexDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/LatexDocumentation/Input/document` | yes | string | — — — — | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/LatexDocumentation/Input/latex_artifact` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/LatexDocumentation/Input/pdf_artifact` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/LatexDocumentation/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/LatexDocumentation/Input/ubuntu_image_version: + +ubuntu_image_version +==================== + +:Type: string +:Required: no +:Default Value: ``'24.04'`` +:Possible Values: See `actions/runner-images - Available Images `__ + for available Ubuntu image versions. +:Description: Version of the Ubuntu image used to run this job. + + .. note:: + + Unfortunately, GitHub Actions has only a `limited set of functions `__, + thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image + version. + +.. _JOBTMPL/LatexDocumentation/Input/document: + +document +======== + +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/LatexDocumentation/Input/latex_artifact: + +latex_artifact ============== -.. todo:: LatexDocumentation:Simple example needs documentation. +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/LatexDocumentation/Input/pdf_artifact: + +pdf_artifact +============ + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/LatexDocumentation/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/LatexDocumentation/Outputs: + +Outputs +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index bf99758..eb234cf 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst @@ -3,20 +3,276 @@ SphinxDocumentation ################### -.. todo:: SphinxDocumentation:Needs documentation. +The ``SphinxDocumentation`` job template .......... -**Behavior:** +.. topic:: Features -.. todo:: SphinxDocumentation:Behavior needs documentation. + * Build documentation using Sphinx as HTML and upload as artifact. |br| + (see :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact`). + * Build documentation using Sphinx as LaTeX and upload as artifact. |br| + (see :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact`). -**Dependencies:** + * Workaround `sphinx-doc/sphinx#13189 `__ + * Workaround `sphinx-doc/sphinx#13190 `__ -.. todo:: SphinxDocumentation:Dependencies needs documentation. + * Optionally: download code coverage artifact (JSON format) given by :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact`. + * Optionally: download unit test report artifact (XML format) given by :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact`. + +.. topic:: Behavior: + + .. todo:: SphinxDocumentation:Behavior needs documentation. + +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-SphinxDocumentation.png + :width: 600px + +.. topic:: Dependencies + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`pyTooling/download-artifact` + + * :gh:`actions/download-artifact` + + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * apt + + * `graphviz `__ + + * pip + + * :pip:`wheel` + * Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements`. + + +.. _JOBTMPL/SphinxDocumentation/Instantiation: Instantiation ************* -Simple Example +The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only +requires a `name` parameter to create the artifact names. + +.. code-block:: yaml + + name: Pipeline + + on: + push: + workflow_dispatch: + + jobs: + UnitTestingParams: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 + with: + package_name: myPackage + + Documentation: + uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r5 + needs: + - UnitTestingParams + with: + python_version: ${{ needs.UnitTestingParams.outputs.python_version }} + html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }} + latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }} + + +.. seealso:: + + :ref:`JOBTMPL/TagReleaseCommit` + ``SphinxDocumentation`` is usualy + +.. _JOBTMPL/SphinxDocumentation/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=========================================================================+==========+==========+===================================================================+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/python_version` | no | string | ``'3.13'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` | no | string | ``'-r doc/requirements.txt'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/doc_directory` | no | string | ``'doc'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory` | no | string | ``'report/unit'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact` | no | string | ``''`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/SphinxDocumentation/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version: + +ubuntu_image_version +==================== + +:Type: string +:Required: no +:Default Value: ``'24.04'`` +:Possible Values: See `actions/runner-images - Available Images `__ + for available Ubuntu image versions. +:Description: Version of the Ubuntu image used to run this job. + + .. note:: + + Unfortunately, GitHub Actions has only a `limited set of functions `__, + thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image + version. + + +.. _JOBTMPL/SphinxDocumentation/Input/python_version: + +python_version ============== -.. todo:: SphinxDocumentation:Simple example needs documentation. +:Type: string +:Required: no +:Default Value: ``'3.13'`` +:Possible Values: Any valid Python version conforming to the pattern ``.`` or ``pypy-.``. |br| + See `actions/python-versions - available Python versions `__ + and `actions/setup-python - configurable Python versions `__. +:Description: Python version used as default for other jobs requiring a single Python version. |br| + In case :ref:`JOBTMPL/Parameters/Input/python_version_list` is an empty string, this version is used + to populate the version list. + + +.. _JOBTMPL/SphinxDocumentation/Input/requirements: + +requirements +============ + +:Type: string +:Required: no +:Default Value: ``'-r doc/requirements.txt'`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Input/doc_directory: + +doc_directory +============= + +:Type: string +:Required: no +:Default Value: ``'doc'`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json_directory: + +coverage_report_json_directory +============================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact: + +coverage_json_artifact +====================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact: + +unittest_xml_artifact +===================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_directory: + +unittest_xml_directory +====================== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Input/html_artifact: + +html_artifact +============= + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Input/latex_artifact: + +latex_artifact +============== + +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: tbd +:Description: tbd + + +.. _JOBTMPL/SphinxDocumentation/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/SphinxDocumentation/Outputs: + +Outputs +******* + +This job template has no output parameters. diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index 04193ff..edc4b48 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -112,11 +112,11 @@ Parameter Summary | :ref:`JOBTMPL/ExtractConfiguration/Input/coverage_config` | no | string | ``'pyproject.toml'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -.. rubric:: Goto Goto :ref:`secrets ` +.. rubric:: Goto :ref:`secrets ` This job template needs no secrets. -.. rubric:: Goto Goto :ref:`output parameters ` +.. rubric:: Goto :ref:`output parameters ` +---------------------------------------------------------------------------------+----------+-------------------------------------------------------------------+ | Result Name | Type | Description | diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index 40216db..8f51751 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -187,11 +187,11 @@ Parameter Summary | :ref:`JOBTMPL/Parameters/Input/pipeline-delay` | no | number | ``0`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -.. rubric:: Goto Goto :ref:`secrets ` +.. rubric:: Goto :ref:`secrets ` This job template needs no secrets. -.. rubric:: Goto Goto :ref:`output parameters ` +.. rubric:: Goto :ref:`output parameters ` +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ | Result Name | Type | Description | diff --git a/doc/JobTemplate/Setup/PrepareJob.rst b/doc/JobTemplate/Setup/PrepareJob.rst index 2defbdb..4f1b48b 100644 --- a/doc/JobTemplate/Setup/PrepareJob.rst +++ b/doc/JobTemplate/Setup/PrepareJob.rst @@ -113,11 +113,11 @@ Parameter Summary | :ref:`JOBTMPL/PrepareJob/Input/release_tag_pattern` | no | string | ``'(v|r)?[0-9]+(\.[0-9]+){0,2}(-(dev|alpha|beta|rc)([0-9]*))?'`` | +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ -.. rubric:: Goto Goto :ref:`secrets ` +.. rubric:: Goto :ref:`secrets ` This job template needs no secrets. -.. rubric:: Goto Goto :ref:`output parameters ` +.. rubric:: Goto :ref:`output parameters ` +---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ | Result Name | Type | Description | diff --git a/doc/_static/pyTooling-Actions-SphinxDocumentation.png b/doc/_static/pyTooling-Actions-SphinxDocumentation.png new file mode 100644 index 0000000..4152136 Binary files /dev/null and b/doc/_static/pyTooling-Actions-SphinxDocumentation.png differ diff --git a/tests/requirements.txt b/tests/requirements.txt index 36106b3..01718d8 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -9,5 +9,5 @@ pytest-cov ~= 6.2 # Static Type Checking mypy ~= 1.17 -typing_extensions ~= 4.14 +typing_extensions ~= 4.15 lxml ~= 6.0