add nox make session and revamp contribution docs (#707) (#917)

This PR adds a `make` session to the noxfile to automate running the
docs build Makefile and revamps the README to document the process. It
also updates the documentation_contributions docs to advise setting up a
venv in the same way that `nox` does.

(cherry picked from commit f1fe1d4c6d)

Co-authored-by: Maxwell G <maxwell@gtmx.me>
Co-authored-by: Don Naro <dnaro@redhat.com>

README.md

@@ -4,44 +4,60 @@ This repository holds the ReStructuredText (RST) source, and other files, for us
 
 > Documentation for modules and plugins that are officially supported by the Ansible Core engineering team is available in the [`ansible/ansible`](https://github.com/ansible/ansible) repository.
 
-## Building Ansible community documentation
-
-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)
-
 ## Verifying your 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.
 
-### Running automated tests
+### Setting up nox
 
 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.
+You can manually
+[set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally)
+if you prefer, but `nox` is more straightforward and create an isolated environment for you.
 
-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.
+* Install `nox` using `python3 -m pip install nox` or your distribution's package manager.
 
-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:
+* Execute `nox` from the repository root with no arguments to run
+  all docs checkers, Python code checkers, and a minimal HTML docs build.
 
-* Run all available sessions.
+* Alternatively, you can run only certain tasks as outlined in the following sections.
+  Run `nox --list` to view available sessions.
 
-  ```
-  nox
-  ```
+### Building docs
+
+The different Makefile targets used to build the documentation are outlined in
+[Building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally).
+The `nox` configuration has a `make` session that creates a build environment and uses the Makefile to generate HTML.
 
 * Clone required parts of the `ansible/ansible` repository.
 
-  ```
+  ``` bash
   nox -s clone-core
   ```
 
   See [Periodically cloning Ansible core](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#periodically-cloning-ansible-core) for more information.
 
+* Build minimal Ansible Core docs.
+
+  ``` bash
+  nox -s make
+  ```
+
+* Run a specific Makefile target:
+
+  ``` bash
+  nox -s make -- clean htmlsingle rst=community/documentation_contributions.rst
+  ```
+
+### Running automated tests
+
+The `nox` configuration also contains session to run automated docs checkers.
+
 * Ensure there are no syntax errors in the reStructuredText source files.
 
-  ```
+  ``` bash
   nox -s "checkers(rstcheck)"
   ```
 
@@ -49,7 +65,7 @@ The following are some of the `nox` sessions you can run:
 
 * Verify the docs build.
 
-  ```
+  ``` bash
   nox -s "checkers(docs-build)"
   ```
 
@@ -59,29 +75,29 @@ The following are some of the `nox` sessions you can run:
 
 * Lint, type check, and format Python scripts in this repository.
 
-  ```
+  ``` bash
   nox -s lint
   ```
 
-## Checking spelling
+### Checking spelling
 
 Use [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source.
 
 * Check spelling.
 
-  ```
+  ``` bash
   nox -s spelling
   ```
 
 * Correct any detected spelling errors.
 
-  ```
+  ``` bash
   nox -s spelling -- -w
   ```
 
 * Select an option when `codespell` suggests more than one word as a correction.
 
-  ```
+  ``` bash
   nox -s spelling -- -w -i 3
   ```
 
@@ -103,7 +119,7 @@ For more details about using unpinned and tested dependencies for doc builds, se
 
 Use the following `nox` session to update the dependency lock files in `tests/`.
 
-  ```
+  ``` bash
   nox -e pip-compile
   ```
 

noxfile.py

@@ -4,6 +4,7 @@ import os
 from argparse import ArgumentParser, BooleanOptionalAction
 from glob import iglob
 from pathlib import Path
+from typing import cast
 
 import nox
 
@@ -13,7 +14,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", "checkers")
+nox.options.sessions = ("clone-core", "lint", "checkers", "make")
 
 
 def install(session: nox.Session, *args, req: str, **kwargs):
@@ -123,11 +124,9 @@ checker_tests = [
 ]
 
 
-@nox.session
-@nox.parametrize(["test"], checker_tests, checker_tests)
-def checkers(session: nox.Session, test: str):
+def _relaxed_parser(session: nox.Session) -> ArgumentParser:
     """
-    Run docs build checkers
+    Generate an argument parser with a --relaxed option.
     """
     parser = ArgumentParser(prog=f"nox -e {session.name} --")
     parser.add_argument(
@@ -136,8 +135,47 @@ def checkers(session: nox.Session, test: str):
         action=BooleanOptionalAction,
         help="Whether to use requirements-relaxed file. (Default: %(default)s)",
     )
-    args = parser.parse_args(session.posargs)
+    return parser
+
+
+def _env_python(session: nox.Session) -> str:
+    """
+    Get the full path to an environment's python executable
+    """
+    out = cast(
+        str,
+        session.run("python", "-c", "import sys; print(sys.executable)", silent=True),
+    )
+    return out.strip()
+
+
+@nox.session
+@nox.parametrize(["test"], checker_tests, checker_tests)
+def checkers(session: nox.Session, test: str):
+    """
+    Run docs build checkers
+    """
+    args = _relaxed_parser(session).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)
+
+
+@nox.session
+def make(session: nox.Session):
+    """
+    Generate HTML from documentation source using the Makefile
+    """
+    parser = _relaxed_parser(session)
+    parser.add_argument(
+        "make_args", nargs="*", help="Specify make targets as arguments"
+    )
+    args = parser.parse_args(session.posargs)
+
+    install(session, req="requirements-relaxed" if args.relaxed else "requirements")
+    make_args: list[str] = [
+        f"PYTHON={_env_python(session)}",
+        *(args.make_args or ("clean", "coredocs")),
+    ]
+    session.run("make", "-C", "docs/docsite", *make_args, external=True)