From 352c8e9e472343bb9ebb70ff8946043ad1b23059 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Fri, 1 Dec 2023 11:50:25 -0600 Subject: [PATCH] improve nox make session docs Co-authored-by: Don Naro --- README.md | 9 ++++----- noxfile.py | 6 ++++-- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 220c2909a3..f4e6ace797 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ This project includes a `nox` configuration to automate tests, checks, and other 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 the `nox` configuration significantly simplifies this process. +if you prefer, but `nox` is more straightforward and create an isolated environment for you. * Install `nox` using `python3 -m pip install nox` or your distribution's package manager. @@ -29,8 +29,7 @@ if you prefer, but the `nox` configuration significantly simplifies this process 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 to automate setting up a docs build -environment and running the Makefile. +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. @@ -40,13 +39,13 @@ environment and running the Makefile. See [Periodically cloning Ansible core](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#periodically-cloning-ansible-core) for more information. -* Run a minimal Ansible Core docs build. +* Build minimal Ansible Core docs. ``` bash nox -s make ``` -* Run a specific Makefile target with options +* Run a specific Makefile target: ``` bash nox -s make -- clean htmlsingle rst=community/documentation_contributions.rst diff --git a/noxfile.py b/noxfile.py index 7ae44d0d86..bc673dfff1 100644 --- a/noxfile.py +++ b/noxfile.py @@ -165,10 +165,12 @@ def checkers(session: nox.Session, test: str): @nox.session def make(session: nox.Session): """ - Run the docs build Makefile in an isolated environment + Generate HTML from documentation source using the Makefile """ parser = _relaxed_parser(session) - parser.add_argument("make_args", nargs="*", help="Arguments to pass on to make") + 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")