diff --git a/.github/workflows/CheckDocumentation.yml b/.github/workflows/CheckDocumentation.yml index c9568ca..d519687 100644 --- a/.github/workflows/CheckDocumentation.yml +++ b/.github/workflows/CheckDocumentation.yml @@ -41,7 +41,7 @@ on: fail_under: description: 'Minimum required documentation coverage level' required: false - default: 80 + default: '80' type: string jobs: @@ -57,7 +57,7 @@ jobs: with: python-version: ${{ inputs.python_version }} - - name: 🔧 Install wheel,tomli and pip dependencies (native) + - name: 🔧 Install docstr_coverage and interrogate dependencies run: | python -m pip install --disable-pip-version-check -U docstr_coverage interrogate[png] @@ -80,4 +80,3 @@ jobs: if [[ $? -ne 0 ]]; then printf "%s\n" "::error title=docstr-coverage::Insufficient documentation quality (goal: ${{ inputs.fail_under }})" fi - diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 48e1b14..acbb949 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -191,6 +191,14 @@ It can be used for simple Python packages as well as namespace packages. * :ref:`pyTooling/Actions/.github/workflows/ApplicationTesting.yml ` * :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * pip + + * :pypi:`docstr_coverage` + * :pypi:`interrogate` + * :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml ` * :ref:`pyTooling/Actions/.github/workflows/Package.yml ` diff --git a/doc/JobTemplate/Documentation/SphinxDocumentation.rst b/doc/JobTemplate/Documentation/SphinxDocumentation.rst index 672f972..99d5465 100644 --- a/doc/JobTemplate/Documentation/SphinxDocumentation.rst +++ b/doc/JobTemplate/Documentation/SphinxDocumentation.rst @@ -161,9 +161,7 @@ python_version :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. +:Description: Python version used to run Python code in this job. .. _JOBTMPL/SphinxDocumentation/Input/requirements: diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index e969655..3fa2a24 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -145,9 +145,7 @@ python_version :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. +:Description: Python version used to run Python code in this job. .. _JOBTMPL/Package/Input/requirements: diff --git a/doc/JobTemplate/Package/PublishOnPyPI.rst b/doc/JobTemplate/Package/PublishOnPyPI.rst index 74a0f0a..eed98e3 100644 --- a/doc/JobTemplate/Package/PublishOnPyPI.rst +++ b/doc/JobTemplate/Package/PublishOnPyPI.rst @@ -167,9 +167,7 @@ python_version :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. +:Description: Python version used to run Python code in this job. .. _JOBTMPL/PublishOnPyPI/Input/requirements: diff --git a/doc/JobTemplate/Quality/CheckDocumentation.rst b/doc/JobTemplate/Quality/CheckDocumentation.rst index fcfc7ae..86088b4 100644 --- a/doc/JobTemplate/Quality/CheckDocumentation.rst +++ b/doc/JobTemplate/Quality/CheckDocumentation.rst @@ -3,20 +3,173 @@ CheckDocumentation ################## -.. todo:: CheckDocumentation:Needs documentation. +The ``CheckDocumentation`` job checks the level of documentation coverage for Python files. -**Behavior:** +.. topic:: Features -.. todo:: CheckDocumentation:Behavior needs documentation. + * Check documentation coverage in Python code using :pypi:`docstr_coverage`. + * Check documentation coverage in Python code using :pypi:`interrogate`. -**Dependencies:** +.. topic:: Behavior -.. todo:: CheckDocumentation:Dependencies needs documentation. + 1. Checkout repository. + 2. Setup Python environment and install dependencies. + 3. Run ``docstr_coverage``. + 3. Run ``interrogate``. + +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-CheckDocumentation.png + :width: 600px + +.. topic:: Dependencies + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * pip + + * :pypi:`docstr_coverage` + * :pypi:`interrogate` + + +.. _JOBTMPL/CheckDocumentation/Instantiation: Instantiation ************* -Simple Example +The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only +requires a `name` parameter to create the artifact names. + +.. code-block:: yaml + + name: Pipeline + + on: + push: + workflow_dispatch: + + jobs: + ConfigParams: + uses: pyTooling/Actions/.github/workflows/ExtractConfiguration.yml@r5 + with: + package_name: myPackage + + DocCoverage: + uses: pyTooling/Actions/.github/workflows/CheckDocumentation.yml@r5 + needs: + - ConfigParams + with: + directory: ${{ needs.ConfigParams.outputs.package_directory }} + + +.. seealso:: + + :ref:`JOBTMPL/ConfigParams` + ``ConfigParams`` is usualy + + +.. _JOBTMPL/CheckDocumentation/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=========================================================================+==========+==========+===================================================================+ +| :ref:`JOBTMPL/CheckDocumentation/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/CheckDocumentation/Input/python_version` | no | string | ``'3.13'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/CheckDocumentation/Input/directory` | yes | string | — — — — | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/CheckDocumentation/Input/fail_under` | no | string | ``'80'`` | ++-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/CheckDocumentation/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/CheckDocumentation/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/CheckDocumentation/Input/python_version: + +python_version ============== -.. todo:: CheckDocumentation: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 to run Python code in this job. + + +.. _JOBTMPL/CheckDocumentation/Input/directory: + +directory +========= + +:Type: string +:Required: yes +:Default Value: — — — — +:Possible Values: Any valid directory or sub-directory. +:Description: Directory where the Python code is located. + + +.. _JOBTMPL/CheckDocumentation/Input/fail_under: + +fail_under +========== + +:Type: string +:Required: no +:Default Value: ``'80'`` +:Possible Values: Any valid percentage from 0 to 100 encoded as string. +:Description: A minimum percentage level for good documentation. If the documentation coverage is below this level, + the coverage is considered a fail. + + +.. _JOBTMPL/CheckDocumentation/Secrets: + +Secrets +******* + +This job template needs no secrets. + + +.. _JOBTMPL/CheckDocumentation/Outputs: + +Outputs +******* + +This job template has no output parameters. diff --git a/doc/_static/pyTooling-Actions-CheckDocumentation.png b/doc/_static/pyTooling-Actions-CheckDocumentation.png new file mode 100644 index 0000000..c3238aa Binary files /dev/null and b/doc/_static/pyTooling-Actions-CheckDocumentation.png differ