mirror of
https://github.com/pyTooling/Actions.git
synced 2026-02-12 19:16:57 +08:00
176 lines
6.0 KiB
ReStructuredText
176 lines
6.0 KiB
ReStructuredText
.. _JOBTMPL/CheckDocumentation:
|
|
|
|
CheckDocumentation
|
|
##################
|
|
|
|
The ``CheckDocumentation`` job checks the level of documentation coverage for Python files.
|
|
|
|
.. topic:: Features
|
|
|
|
* Check documentation coverage in Python code using :pypi:`docstr_coverage`.
|
|
* Check documentation coverage in Python code using :pypi:`interrogate`.
|
|
|
|
.. topic:: Behavior
|
|
|
|
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
|
|
*************
|
|
|
|
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 <JOBTMPL/CheckDocumentation/Inputs>`
|
|
|
|
+-------------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
|
|
| 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 <JOBTMPL/CheckDocumentation/Secrets>`
|
|
|
|
This job template needs no secrets.
|
|
|
|
.. rubric:: Goto :ref:`output parameters <JOBTMPL/CheckDocumentation/Outputs>`
|
|
|
|
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 <https://github.com/actions/runner-images?tab=readme-ov-file#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 <https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#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
|
|
==============
|
|
|
|
:Type: string
|
|
:Required: no
|
|
:Default Value: ``'3.13'``
|
|
:Possible Values: Any valid Python version conforming to the pattern ``<major>.<minor>`` or ``pypy-<major>.<minor>``. |br|
|
|
See `actions/python-versions - available Python versions <https://github.com/actions/python-versions>`__
|
|
and `actions/setup-python - configurable Python versions <https://github.com/actions/setup-python>`__.
|
|
: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.
|