mirror of
https://github.com/pyTooling/Actions.git
synced 2026-02-12 19:16:57 +08:00
151 lines
5.0 KiB
ReStructuredText
151 lines
5.0 KiB
ReStructuredText
.. _JOBTMPL/CheckDocumentation:
|
|
.. index::
|
|
single: docstr_coverage; CheckDocumentation Template
|
|
single: interrogate; CheckDocumentation Template
|
|
single: GitHub Action Reusable Workflow; CheckDocumentation Template
|
|
|
|
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``.
|
|
4. 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
|
|
|
|
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/ExtractConfiguration`
|
|
``ExtractConfiguration`` is usually used to compute the path to the package's source code directory.
|
|
|
|
|
|
.. _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:
|
|
|
|
.. include:: ../_ubuntu_image_version.rst
|
|
|
|
|
|
.. _JOBTMPL/CheckDocumentation/Input/python_version:
|
|
|
|
.. include:: ../_python_version.rst
|
|
|
|
|
|
.. _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.
|