README: document new nox sessions

Co-authored-by: Maxwell G <maxwell@gtmx.me>

README.md

@@ -8,30 +8,67 @@ 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
+## Testing your changes
 
-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 first run tests from this repository.
+Doing so ensures that your pull request does not trigger any ci failures.
 
-Install `nox` using `python3 -m pip install nox` or your distribution's package manager.
+## Preparing to run 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.
 
-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.
 
-This repository uses [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source.
+## Running all tests
 
-Run `nox -s spelling` to check spelling.
+Run `nox` with no arguments to run all available sessions.
 
-Run `nox -s spelling -- -w` to correct spelling errors.
+## Cloning required parts of the Ansible core repository
 
-When `codespell` suggests more than one word as a correction, run `nox -s spelling -- -w -i 3` to select an option.
+As mentioned in the [local build documentation](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally), you should periodically clone required parts of the `ansible/ansible` repository.
 
-## Updating the dependencies
+Run `nox -s clone-core`.
+
+## Running the docs-build checker
+
+Ensure your changes do not introduce errors and the docs build succeeds.
+
+1. Clone parts of the `ansible/ansible` repository with `nox -s clone-core`.
+2. Run `nox -s "checkers(docs-build)"`.
+
+You can also run `nox -s "checkers(docs-build)" -- --relaxed` if you want to test against unpinned requirements.
+
+> The docs-build 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.
+
+## Checking RST syntax
+
+Use [`rstcheck`](https://pypi.org/project/rstcheck/) to ensure there are no syntax errors in the reStructuredText source files.
+
+Run `nox -s "checkers(rstcheck)"`.
+
+## Checking spelling
+
+Use [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source.
+
+* Run `nox -s spelling` to check spelling.
+* Run `nox -s spelling -- -w` to correct spelling errors.
+
+> When `codespell` suggests more than one word as a correction, run `nox -s spelling -- -w -i 3` to select an option.
+
+## Updating dependencies
+
+Run `nox -e pip-compile` to update project dependency versions.
+
+> 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'
 ```