pyTooling/Actions
1
0
Fork 0
mirror of https://github.com/pyTooling/Actions.git synced 2026-02-12 11:06:56 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
r7
Actions/doc/JobTemplate/Documentation/SphinxDocumentation.rst
Patrick Lehmann 497307f0e4 Updating r7 from v7.0.1
2025-12-20 00:45:52 +01:00

328 lines
13 KiB
ReStructuredText
Raw Permalink Blame History

.. _JOBTMPL/SphinxDocumentation:
.. index::
single: Sphinx; SphinxDocumentation Template
single: GitHub Action Reusable Workflow; SphinxDocumentation Template
SphinxDocumentation
###################
The ``SphinxDocumentation`` job template compiles the ReStructured Text documentation using :term:`Sphinx` to an HTML
website and a LaTeX documentation. This LaTeX document can be translated using e.g. :term:`MikTeX` to a PDF file.
.. topic:: Features
* 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`).
* Workaround `sphinx-doc/sphinx#13189 <https://github.com/sphinx-doc/sphinx/issues/13189>`__
* Workaround `sphinx-doc/sphinx#13190 <https://github.com/sphinx-doc/sphinx/issues/13190>`__
* 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
1. Checkout repository.
2. Install system dependencies.
3. Setup Python environment and install Python dependencies.
4. Download optional artifacts for integration of further reports into the documentation.
5. Build the HTML documentation using Sphinx.
6. Build the LaTeX documentation using Sphinx.
1. Apply LaTeX workaround I.
2. Apply LaTeX workaround II.
7. Upload the HTML and LaTeX artifacts.
.. 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 <https://graphviz.org/>`__
* pip
* :pypi:`wheel`
* Python packages specified via :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` parameter.
.. _JOBTMPL/SphinxDocumentation/Instantiation:
Instantiation
*************
.. code-block:: yaml
jobs:
UnitTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r7
with:
package_name: myPackage
Documentation:
uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r7
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 }}
.. _JOBTMPL/SphinxDocumentation/Parameters:
Parameter Summary
*****************
.. rubric:: Goto :ref:`input parameters <JOBTMPL/SphinxDocumentation/Inputs>`
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
| 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.14'`` |
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
| :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_json_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/SphinxDocumentation/Input/coverage_report_json` | no | string (JSON) | :jsoncode:`{"directory": "report/coverage"}` |
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/SphinxDocumentation/Input/unittest_xml` | no | string (JSON) | :jsoncode:`{"directory": "report/unit"}` |
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact` | no | string | ``''`` |
+-------------------------------------------------------------------------+----------+----------------+-------------------------------------------------------------------+
.. rubric:: Goto :ref:`secrets <JOBTMPL/SphinxDocumentation/Secrets>`
This job template needs no secrets.
.. rubric:: Goto :ref:`output parameters <JOBTMPL/SphinxDocumentation/Outputs>`
This job template has no output parameters.
.. _JOBTMPL/SphinxDocumentation/Inputs:
Input Parameters
****************
.. _JOBTMPL/SphinxDocumentation/Input/ubuntu_image_version:
.. include:: ../_ubuntu_image_version.rst
.. _JOBTMPL/SphinxDocumentation/Input/python_version:
.. include:: ../_python_version.rst
.. _JOBTMPL/SphinxDocumentation/Input/requirements:
requirements
============
:Type: string
:Required: no
:Default Value: ``'-r doc/requirements.txt'``
:Possible Values: Any valid list of parameters for ``pip install``. |br|
Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of
packages can be specified using a space separated list like ``'Sphinx sphinx_rtd_theme sphinxcontrib-mermaid'``.
:Description: Python dependencies to be installed through *pip*.
.. _JOBTMPL/SphinxDocumentation/Input/doc_directory:
doc_directory
=============
:Type: string
:Required: no
:Default Value: ``'doc'``
:Possible Values: Any valid directory or sub-directory.
:Description: Directory where the Sphinx documentation is located.
.. attention::
When this parameter gets changed, :ref:`JOBTMPL/SphinxDocumentation/Input/requirements` needs to be
adjusted as well.
.. _JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact:
coverage_json_artifact
======================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid artifact name.
:Description: Name of the artifact containing the code coverage report in JSON format.
.. _JOBTMPL/SphinxDocumentation/Input/coverage_report_json:
coverage_report_json
====================
:Type: string (JSON)
:Required: no
:Default Value:
.. code-block:: json
{ "directory": "reports/coverage",
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
:directory: Directory or sub-directory where the code coverage JSON report will be extracted from
:ref:`artifact <JOBTMPL/SphinxDocumentation/Input/coverage_json_artifact>`.
:Description: Directory as JSON object where the code coverage JSON report will be extracted. |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@r7
Documentation:
uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r7
needs:
- ConfigParams
with:
...
coverage_report_json: ${{ needs.ConfigParams.outputs.coverage_report_json }}
.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact:
unittest_xml_artifact
=====================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid artifact name.
:Description: Name of the artifact containing the unittest XML report summary in XML format.
.. _JOBTMPL/SphinxDocumentation/Input/unittest_xml:
unittest_xml
============
:Type: string (JSON)
:Required: no
:Default Value:
.. code-block:: json
{ "directory": "reports/unit",
}
:Possible Values: Any valid JSON string containing a JSON object with fields:
:directory: Directory or sub-directory where the unittest JUnit XML report will be extracted from
:ref:`artifact <JOBTMPL/SphinxDocumentation/Input/unittest_xml_artifact>`.
:Description: Directory as JSON object where the unittest JUnit XML report will be extracted. |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@r7
Documentation:
uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@r7
needs:
- ConfigParams
with:
...
unittest_xml: ${{ needs.ConfigParams.outputs.unittest_xml }}
.. _JOBTMPL/SphinxDocumentation/Input/html_artifact:
html_artifact
=============
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid artifact name.
:Description: Name of the artifact containing the generated HTML website.
:Optimization:
.. hint::
If this parameter is empty, no HTML website will be generated and no artifact will be uploaded.
.. _JOBTMPL/SphinxDocumentation/Input/latex_artifact:
latex_artifact
==============
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid artifact name.
:Description: Name of the artifact containing the generated LaTeX document and resource files (e.g., images).
:Optimization:
.. hint::
If this parameter is empty, no LaTeX document will be generated and no artifact will be uploaded.
.. _JOBTMPL/SphinxDocumentation/Secrets:
Secrets
*******
This job template needs no secrets.
.. _JOBTMPL/SphinxDocumentation/Outputs:
Outputs
*******
This job template has no output parameters.
.. _JOBTMPL/SphinxDocumentation/Optimizations:
Optimizations
*************
The following optimizations can be used to reduce the template's runtime.
Disable HTML website generation and HTML artifact
If parameter :ref:`JOBTMPL/SphinxDocumentation/Input/html_artifact` is empty, no HTML website will be generated and
uploaded.
Disable LaTeX document generation and LaTeX artifact
If parameter :ref:`JOBTMPL/SphinxDocumentation/Input/latex_artifact` is empty, no LaTeX document will be generated and
uploaded.
Reference in New Issue View Git Blame Copy Permalink