Update docs on documentation check workflow

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 <run-documentation-checks>`.
+
+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 <target>``.
+
+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
+

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 <openapi-specifications>
     Add interactive tables <interactive-tables>
     external-referencing-intersphinx
-
-
+    customize-documentation-check-ci
 

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
+<modify-documentation-check-workflow>` or :ref:`run documentation checks locally
+<run-documentation-checks>`.
+
+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.