diff --git a/docs/how-to/optional-customisation/customize-documentation-check-ci.rst b/docs/how-to/optional-customisation/customize-documentation-check-ci.rst new file mode 100644 index 0000000..e3966b5 --- /dev/null +++ b/docs/how-to/optional-customisation/customize-documentation-check-ci.rst @@ -0,0 +1,112 @@ +:relatedlinks: https://docs.github.com/en/actions/reference/workflows-and-actions + +.. meta:: + :description: How to modify the Sphinx Stack's default GitHub workflow for documentation checks. + +.. _modify-documentation-check-workflow: + +Customize the documentation check CI +==================================== + +The Sphinx Stack provides a GitHub Actions workflow, +``.github/workflows/documentation-checks.yaml``, to automate spelling, link, and +inclusive language checks. This guide describes how to configure the working +directory and Python version, and how to add or remove documentation checks. + +You can also :ref:`run these checks locally `. + +Change the working directory +---------------------------- + +By default, the workflow uses ``docs`` as the documentation directory. If +your documentation is located in a different directory, you must modify +``documentation-checks.yaml`` in two places: + +* The workflow is configured to run on pull requests that modify files in the + ``docs`` directory. Find the ``"docs/**"`` string under + ``on.pull_request.paths``, and replace ``docs`` with the path to your + documentation. For example, you can change the documentation directory from + ``docs`` to ``doc``: + + .. code-block:: diff + + on: + push: + branches: + - main + pull_request: + paths: + - - "docs/**" + + - "doc/**" + +* In the remainder of ``documentation-checks.yaml``, the working directory is + configured with the ``DOCS_DIR`` environment variable set under ``env``. + Change the value of ``DOCS_DIR`` from ``"docs"`` to the path to your + documentation. + + .. code-block:: diff + + env: + - DOCS_DIR: "docs" + + DOCS_DIR: "doc" + PYTHON_VERSION: "3.10" + + .. note:: + + Do not include a trailing slash character when changing the value of + the ``DOCS_DIR`` variable. + +Modify the Python version +------------------------- + +The Python version is configured with the ``PYTHON_VERSION`` environment +variable set under ``env``. Change this value to use a different version: + +.. code-block:: diff + + env: + DOCS_DIR: "docs" + DOCS_DIR: "doc" + - PYTHON_VERSION: "3.10" + + PYTHON_VERSION: "3.12" + +.. note:: + + Place the Python version number in quotation marks. Version numbers without + quotation marks will be parsed as floating-point numbers, and the GitHub + Action will fail. + +Add or remove a Makefile target +------------------------------- + +The ``documentation-checks.yaml`` workflow uses a matrix strategy to run three +jobs in parallel: the spelling, links, and inclusive language checks. Each +check in the matrix defines a ``name`` and a ``target``. The ``name`` is how the +check is listed when it runs on GitHub, and the ``target`` corresponds to a Make +target defined in the Sphinx Stack ``Makefile``. The job itself consists of a +single command: ``make ``. + +To add a new ``Makefile`` target to the matrix, add a ``name`` and ``target`` +pair to the array under ``jobs.checks.strategy.matrix.check``. To remove a +check, simply remove the lines containing the check's ``name`` and ``target``. +For example, you can remove the spelling check and add a style guide check: + +.. code-block:: diff + + jobs: + checks: + name: ${{ matrix.check.name }} + runs-on: ubuntu-24.04 + strategy: + fail-fast: false + matrix: + check: + - - name: Spelling check + - target: spelling + + - name: Style guide check + + target: vale + - name: Link check + target: linkcheck + - name: Inclusive language check + target: woke + diff --git a/docs/how-to/optional-customisation/index.rst b/docs/how-to/optional-customisation/index.rst index 18a0e5e..cf716dd 100644 --- a/docs/how-to/optional-customisation/index.rst +++ b/docs/how-to/optional-customisation/index.rst @@ -23,6 +23,5 @@ This includes adding extensions, modifying the build process, and adding custom Add OpenAPI specifications Add interactive tables external-referencing-intersphinx - - + customize-documentation-check-ci diff --git a/docs/reference/github-workflows.rst b/docs/reference/github-workflows.rst index 8694da8..2b4cb9e 100644 --- a/docs/reference/github-workflows.rst +++ b/docs/reference/github-workflows.rst @@ -7,96 +7,60 @@ GitHub workflows ================ -The primary documentation workflow checks spelling, links, and inclusive language in a -documentation project; these are the same checks as described in -:ref:`run-documentation-checks`. - -The ``documentation-checks.yaml`` workflow covers these three checks and can be added to -a new or existing workflow's jobs with: - -.. code:: yaml - - jobs: - [...] - documentation-checks: - uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main - with: - working-directory: 'docs' - - -Workflows are also available for each individual check so that projects may run a subset -of those defined in ``documentation-checks.yaml``: - -.. code:: yaml - - jobs: - spell-check: - uses: canonical/documentation-workflows/.github/workflows/spelling-check.yaml@main - with: - working-directory: "docs" - inclusive-language-check: - uses: canonical/documentation-workflows/.github/workflows/inclusive-language-check.yaml@main - with: - working-directory: "docs" - link-check: - uses: canonical/documentation-workflows/.github/workflows/link-check.yaml@main - with: - working-directory: "docs" - - -Input ------ - -The table below lists the inputs for the ``documentation-checks.yaml`` workflow. If your -project consumes the Sphinx Stack in a non-traditional way, declare any of the following -inputs to customize the workflow as needed: +The Sphinx Stack provides several GitHub Actions workflows to run checks on +documentation projects. + +Spelling, link, and inclusive language checks +--------------------------------------------- + +The ``documentation-checks.yaml`` workflow runs several checks that correspond +to targets in the Sphinx Stack ``Makefile``: + +* Spelling check (``spelling``) +* Link check (``linkcheck``) +* Inclusive language check (``woke``) + +Refer to the how-to guides for details about how to :ref:`modify this workflow +` or :ref:`run documentation checks locally +`. + +Default configuration +~~~~~~~~~~~~~~~~~~~~~ + +The documentation workflow is configured as follows: .. list-table:: :header-rows: 1 - * - Input + * - Key - Description - Default * - ``working-directory`` - - The root of the documentation project. This input is required. - - None + - The root of the documentation project. + - ``docs`` * - ``python-version`` - The Python interpreter to use for the workflow's jobs. - - The default Python version use. Example: ``'3.10'`` + - ``3.10`` * - ``fetch-depth`` - The number of commits to fetch from your repository. - - The full history is fetched. + - ``0`` (the full history is fetched) * - ``runs-on`` - The host system for the workflow's runners. - - The current Ubuntu LTS. Example: ``'["ubuntu-24.04"]'`` - * - ``makefile`` - - The Makefile that checks are invoked from. - - ``'Makefile'`` - * - ``install-target`` - - The make target for installing required tools. - - ``'install'`` - * - ``spelling-target`` - - The make target to run for the spelling check. - - ``'spelling'`` - * - ``woke-target`` - - The make target to run for the inclusive language check. - - ``'woke'`` - * - ``linkcheck-target`` - - The make target to run for the link check. - - ``'linkcheck'`` - + - ``ubuntu-24.04`` Check for removed URLs ---------------------- .. versionadded:: 1.2.0 -The Sphinx Stack includes a GitHub action to identify when pages have been removed. This -includes moving pages to another path, or removing them completely. +The Sphinx Stack includes a GitHub Actions workflow to identify when pages have +been removed. This includes moving pages to another path, or removing them +completely. -This does not cover higher-level changes to URL paths, such as changes to the project -name or URL slug pattern on RTD. +This does not cover higher-level changes to URL paths, such as changes to the +project name or URL slug pattern on RTD. -This check ensures that redirects are implemented when pages are moved, or appropriate -information is provided when anything is removed. It only runs on pull request builds. +This check ensures that redirects are implemented when pages are moved, or +appropriate information is provided when anything is removed. It only runs on +pull request builds.