Document the nox envs.

Julian · Julian · commit cd886db91449 · 2023-09-10T09:56:58.000-04:00
diff --git a/noxfile.py b/noxfile.py
@@ -33,7 +33,7 @@
 nox.options.sessions = []
 
 
-def session(default=True, **kwargs):
+def session(default=True, **kwargs):  # noqa: D103
     def _session(fn):
         if default:
             nox.options.sessions.append(kwargs.get("name", fn.__name__))
@@ -45,7 +45,9 @@ def _session(fn):
 @session(python=["3.8", "3.9", "3.10", "3.11", "3.12", "pypy3"])
 @nox.parametrize("installable", INSTALLABLE)
 def tests(session, installable):
-
+    """
+    Run the test suite with a corresponding Python version.
+    """
     env = dict(JSON_SCHEMA_TEST_SUITE=str(ROOT / "json"))
 
     session.install("virtue", installable)
@@ -87,6 +89,9 @@ def tests(session, installable):
 @session()
 @nox.parametrize("installable", INSTALLABLE)
 def audit(session, installable):
+    """
+    Audit dependencies for vulnerabilities.
+    """
     session.install("pip-audit", installable)
     session.run("python", "-m", "pip_audit")
 
@@ -107,6 +112,9 @@ def audit(session, installable):
 
 @session(tags=["build"])
 def build(session):
+    """
+    Build a distribution suitable for PyPI and check its validity.
+    """
     session.install("build", "docutils", "twine")
     with TemporaryDirectory() as tmpdir:
         session.run("python", "-m", "build", ROOT, "--outdir", tmpdir)
@@ -118,18 +126,27 @@ def build(session):
 
 @session()
 def secrets(session):
+    """
+    Check for accidentally committed secrets.
+    """
     session.install("detect-secrets")
     session.run("detect-secrets", "scan", ROOT)
 
 
 @session(tags=["style"])
 def style(session):
+    """
+    Check Python code style.
+    """
     session.install("ruff")
     session.run("ruff", "check", ROOT)
 
 
 @session()
 def typing(session):
+    """
+    Check static typing.
+    """
     session.install("mypy", "types-requests", ROOT)
     session.run("mypy", "--config", PYPROJECT, PACKAGE)
 
@@ -149,6 +166,9 @@ def typing(session):
     ],
 )
 def docs(session, builder):
+    """
+    Build the documentation using a specific Sphinx builder.
+    """
     session.install("-r", DOCS / "requirements.txt")
     with TemporaryDirectory() as tmpdir_str:
         tmpdir = Path(tmpdir_str)
@@ -170,6 +190,9 @@ def docs(session, builder):
 
 @session(tags=["docs", "style"], name="docs(style)")
 def docs_style(session):
+    """
+    Check the documentation style.
+    """
     session.install(
         "doc8",
         "pygments",
@@ -178,12 +201,6 @@ def docs_style(session):
     session.run("python", "-m", "doc8", "--config", PYPROJECT, DOCS)
 
 
-@session(default=False)
-def bandit(session):
-    session.install("bandit")
-    session.run("bandit", "--recursive", PACKAGE)
-
-
 @session(default=False)
 @nox.parametrize(
     "benchmark",
@@ -193,6 +210,9 @@ def bandit(session):
     ],
 )
 def perf(session, benchmark):
+    """
+    Run a performance benchmark.
+    """
     session.install("pyperf", f"{ROOT}[format]")
     tmpdir = Path(session.create_tmp())
     output = tmpdir / f"bench-{benchmark}.json"
@@ -201,6 +221,11 @@ def perf(session, benchmark):
 
 @session(default=False)
 def requirements(session):
+    """
+    Update the project's pinned requirements.
+
+    You should commit the result afterwards.
+    """
     session.install("pip-tools")
     for each in [DOCS / "requirements.in"]:
         session.run(
diff --git a/pyproject.toml b/pyproject.toml
@@ -180,7 +180,7 @@ extend-exclude = ["json"]
 docstring-quotes = "double"
 
 [tool.ruff.per-file-ignores]
-"noxfile.py" = ["ANN", "D"]
+"noxfile.py" = ["ANN", "D100"]
 "docs/*" = ["ANN", "D"]
 "jsonschema/cli.py" = ["D", "SIM", "UP"]
 "jsonschema/_utils.py" = ["D"]
