Integrate docs checkers into the noxfile (#668)

## Run docs checkers in the noxfile

This adds a checkers session to the noxfile to run docs checkers in
tests/checkers.py.
`nox -e checkers` runs all the docs checkers.
`nox -e 'checkers(rstcheck)'` and `nox -e 'checkers(docs-build)'` can
also be used to call individual checkers.

Simply executing `nox` will clone ansible-core, run the Python linters,
and the docs checkers (docs build test, rstcheck).
This makes it a lot easier for contributors,
as they can just run one command to make sure there changes will pass CI
before submitting a PR
and don't need to muck around with virtual environments and
dependencies.

##  Use nox checkers session in CI 

Now that the docs checkers are integrated into the noxfile, we can use
the nox session in CI instead of having to maintain separate CI
configurations for these jobs.

This change will cause branch protection to fail, as we no longer have
the docs-build and rstcheck CI jobs. I'll fix that when we're ready to
merge this.

Co-authored-by: Don Naro <dnaro@redhat.com>

.github/workflows/ci.yaml

@@ -9,53 +9,5 @@ on:
   workflow_dispatch:
 
 jobs:
-  docs_sanity_docs_build:
-    name: docs-build
-    runs-on: ubuntu-22.04
-    steps:
-    - name: Checkout Docsite
-      uses: actions/checkout@v4
-
-    - name: Install Python 3.11
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.11'
-
-    - name: Install Test Requirements
-      run: |
-        python -m pip install -r tests/requirements.in -c tests/requirements.txt
-
-    - name: Graft ansible-core
-      run: |
-        python docs/bin/clone-core.py
-
-    - name: Run docs-build Checkers
-      run: |
-        python tests/checkers.py docs-build
-
-  docs_sanity_rstcheck:
-    name: rstcheck
-    runs-on: ubuntu-22.04
-    steps:
-    - name: Checkout Docsite
-      uses: actions/checkout@v4
-
-    - name: Install Python 3.11
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.11'
-
-    - name: Install Test Requirements
-      run: |
-        python -m pip install -r tests/requirements.in -c tests/requirements.txt
-
-    - name: Graft ansible-core
-      run: |
-        python docs/bin/clone-core.py
-
-    - name: Run rstcheck Checkers
-      run: |
-        python tests/checkers.py rstcheck
-
   nox:
     uses: ./.github/workflows/reusable-nox.yml

.github/workflows/reusable-nox.yml

@@ -19,6 +19,10 @@ jobs:
             python-versions: "3.11"
           - session: spelling
             python-versions: "3.11"
+          - session: "checkers(rstcheck)"
+            python-versions: "3.11"
+          - session: "checkers(docs-build)"
+            python-versions: "3.11"
     name: "Run nox ${{ matrix.session }} session"
     steps:
       - name: Check out repo
@@ -27,6 +31,9 @@ jobs:
         uses: wntrblm/nox@2023.04.22
         with:
           python-versions: "${{ matrix.python-versions }}"
+      - name: Graft ansible-core
+        run: |
+          nox -e clone-core
       - name: "Run nox -e ${{ matrix.session }}"
         run: |
           nox -e "${{ matrix.session }}"

README.md

@@ -8,30 +8,95 @@ This repository holds the ReStructuredText (RST) source, and other files, for us
 
 Follow the documentation to [set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally) and then [build Ansible community documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally)
 
-## Using nox
+## Verifying your pull request
 
-This project includes a `nox` configuration to automate checks and other functions.
-You should use `nox` to run checks locally before you submit a pull request.
+We welcome all contributions to Ansible community documentation.
+If you plan to submit a pull request with changes, you should [verify your PR](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#verifying-your-documentation-pr) to ensure it conforms with style guidelines and can build successfully.
 
-Install `nox` using `python3 -m pip install nox` or your distribution's package manager.
+### Running automated tests
 
-Run `nox --list` from the repository root to view available sessions.
+This project includes a `nox` configuration to automate tests, checks, and other functions.
+You can use these automated tests to help you verify changes before you submit a PR.
 
-Run `nox` with no arguments to execute the default sessions.
+1. Install `nox` using `python3 -m pip install nox` or your distribution's package manager.
+2. Run `nox --list` from the repository root to view available sessions.
 
-## Running the spelling check
+Each `nox` session creates a temporary environment that installs all requirements and runs the test or check.
+This means you only need to run one command to perform the test accurately and consistently.
+The following are some of the `nox` sessions you can run:
 
-This repository uses [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source.
+* Run all available sessions.
 
-Run `nox -s spelling` to check spelling.
+  ```
+  nox
+  ```
 
-Run `nox -s spelling -- -w` to correct spelling errors.
+* Clone required parts of the `ansible/ansible` repository.
 
-When `codespell` suggests more than one word as a correction, run `nox -s spelling -- -w -i 3` to select an option.
+  ```
+  nox -s clone-core
+  ```
 
-## Updating the dependencies
+  See [Periodically cloning Ansible core](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#periodically-cloning-ansible-core) for more information.
+
+* Ensure there are no syntax errors in the reStructuredText source files.
+
+  ```
+  nox -s "checkers(rstcheck)"
+  ```
+
+  See [Running the final tests](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#running-the-final-tests) for more information.
+
+* Verify the docs build.
+
+  ```
+  nox -s "checkers(docs-build)"
+  ```
+
+  This session cleans the generated docs after it runs.
+  If you want to view the generated HTML in your browser, you should build the documentation locally.
+  See [Building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) for more information.
+
+* Lint, type check, and format Python scripts in this repository.
+
+  ```
+  nox -s lint
+  ```
+
+## Checking spelling
+
+Use [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source.
+
+* Check spelling.
+
+  ```
+  nox -s spelling
+  ```
+
+* Correct any detected spelling errors.
+
+  ```
+  nox -s spelling -- -w
+  ```
+
+* Select an option when `codespell` suggests more than one word as a correction.
+
+  ```
+  nox -s spelling -- -w -i 3
+  ```
+
+## Updating dependencies
+
+Use the following `nox` session to update project dependency versions.
+
+  ```
+  nox -e pip-compile
+  ```
+
+> This session requires Python 3.10.
+
+If you do not have Python 3.10 installed, you can use root-less podman with a Python 3.10 image as follows:
 
-To update dependencies, you can use `nox -e pip-compile`. Since this requires Python 3.10, this might not work in your environment if you do not have Python 3.10 installed. In that case, you can use root-less podman with a Python 3.10 image:
 ```bash
-podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt python:3.10 bash -c 'pip install nox ; nox -e pip-compile'
+podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt docker.io/library/python:3.10 bash -c 'pip install nox ; nox -e pip-compile'
 ```

noxfile.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+from argparse import ArgumentParser, BooleanOptionalAction
 from glob import iglob
 from pathlib import Path
 
@@ -12,7 +13,7 @@ LINT_FILES: tuple[str, ...] = (
     *iglob("docs/bin/*.py"),
 )
 PINNED = os.environ.get("PINNED", "true").lower() in {"1", "true"}
-nox.options.sessions = ("clone-core", "lint")
+nox.options.sessions = ("clone-core", "lint", "checkers")
 
 
 def install(session: nox.Session, *args, req: str, **kwargs):
@@ -113,3 +114,28 @@ def clone_core(session: nox.Session):
     source tree to facilitate building docs.
     """
     session.run_always("python", "docs/bin/clone-core.py")
+
+
+checker_tests = [
+    path.with_suffix("").name for path in Path("tests/checkers/").glob("*.py")
+]
+
+
+@nox.session
+@nox.parametrize(["test"], checker_tests, checker_tests)
+def checkers(session: nox.Session, test: str):
+    """
+    Run docs build checkers
+    """
+    parser = ArgumentParser(prog=f"nox -e {session.name} --")
+    parser.add_argument(
+        "--relaxed",
+        default=False,
+        action=BooleanOptionalAction,
+        help="Whether to use requirements-relaxed file. (Default: %(default)s)",
+    )
+    args = parser.parse_args(session.posargs)
+
+    install(session, req="requirements-relaxed" if args.relaxed else "requirements")
+    session.run("make", "-C", "docs/docsite", "clean", external=True)
+    session.run("python", "tests/checkers.py", test)