README: document new nox sessions

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

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'
 ```