diff --git a/README.md b/README.md index b88530961f..f4e6ace797 100644 --- a/README.md +++ b/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 ``` diff --git a/noxfile.py b/noxfile.py index 2f6df57159..bc673dfff1 100644 --- a/noxfile.py +++ b/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)