From b90724a6413d7f3c2cda758ac5d517e05026ad38 Mon Sep 17 00:00:00 2001 From: Elijah Greenstein Date: Wed, 9 Sep 2026 16:24:12 -0700 Subject: [PATCH] Update docs on documentation check workflow This commit updates the documentation for the GitHub workflow that runs the spelling, link, and inclusive language checks. - Adds a new how-to guide, with instructions for how to make common modifications to the workflow - Updates the GitHub workflows reference page This is based on an update to the Sphinx Stack that incorporates the workflow directly into the Sphinx Stack repo, rather than using callable workflows from the `documentation-workflows` repository. Signed-off-by: Elijah Greenstein --- .../customize-documentation-check-ci.rst | 112 ++++++++++++++++++ docs/how-to/optional-customisation/index.rst | 3 +- docs/reference/github-workflows.rst | 106 ++++++----------- 3 files changed, 148 insertions(+), 73 deletions(-) create mode 100644 docs/how-to/optional-customisation/customize-documentation-check-ci.rst 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.