nox and README: log PIP_CONSTRAINT value and add Dependency file docs (…

…#730) noxfile install(): log PIP_CONSTRAINT value --------------------------------------------------------------- When pinned dependencies are enabled (the default), this will log the value of the PIP_CONSTRAINT env var. README: document Dependency files and PINNED envvar ------------------------------------------------------------------------------------ This documents the way dependency files are organized and handled by nox. --- Co-authored-by: Don Naro <[email protected]> Suggested-by: Don Naro <[email protected]> Ref: https://github.com/ansible/ansible-documentation/pull/668/files#r1371558583
ansible · Oct 26, 2023 · b274c97 · b274c97
2 parents 8d84704 + 30f0a7c
commit b274c97
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -85,9 +85,23 @@ Use [`codespell`](https://github.com/codespell-project/codespell) to check for c
   nox -s spelling -- -w -i 3
   ```
 
+## Dependency files
+
+`nox` sessions use dependencies from requirements files in the `tests/` directory.
+Each session has a `tests/{name}.in` file with direct dependencies and a lock file in `tests/{name}.txt` that pins *exact versions* for both direct and transitive dependencies.
+The lock files contain tested dependencies that are automatically updated on a weekly basis.
+
+If you'd like to use untested dependencies, set `PINNED=false` as in the following example:
+
+```
+PINNED=false nox -s "checkers(docs-build)"
+```
+
+For more details about using unpinned and tested dependencies for doc builds, see [Setting up your environment to build documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally).
+
 ## Updating dependencies
 
-Use the following `nox` session to update project dependency versions.
+Use the following `nox` session to update the dependency lock files in `tests/`.
 
   ```
   nox -e pip-compile

diff --git a/noxfile.py b/noxfile.py
@@ -18,7 +18,9 @@
 
 def install(session: nox.Session, *args, req: str, **kwargs):
     if PINNED:
-        kwargs.setdefault("env", {})["PIP_CONSTRAINT"] = f"tests/{req}.txt"
+        pip_constraint = f"tests/{req}.txt"
+        kwargs.setdefault("env", {})["PIP_CONSTRAINT"] = pip_constraint
+        session.log(f"export PIP_CONSTRAINT={pip_constraint!r}")
     session.install("-r", f"tests/{req}.in", *args, **kwargs)