Add and ensure the noxfile gets documented.

Author: Julian

noxfile.py

@@ -13,7 +13,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__))
@@ -24,6 +24,9 @@ def _session(fn):
 
 @session(python=["3.8", "3.9", "3.10", "3.11", "3.12", "pypy3"])
 def tests(session):
+    """
+    Run the test suite with a corresponding Python version.
+    """
     session.install("-r", ROOT / "test-requirements.txt")
 
     if session.posargs and session.posargs[0] == "coverage":
@@ -52,12 +55,18 @@ def tests(session):
 
 @session()
 def audit(session):
+    """
+    Audit dependencies for vulnerabilities.
+    """
     session.install("pip-audit", ROOT)
     session.run("python", "-m", "pip_audit")
 
 
 @session(tags=["build"])
 def build(session):
+    """
+    Build a distribution suitable for PyPI and check its validity.
+    """
     session.install("build", "twine")
     with TemporaryDirectory() as tmpdir:
         session.run("python", "-m", "build", ROOT, "--outdir", tmpdir)
@@ -66,12 +75,18 @@ def build(session):
 
 @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("pyright==1.1.307", ROOT)
     session.run("pyright", REFERENCING)
 
@@ -91,6 +106,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)
@@ -112,6 +130,9 @@ def docs(session, builder):
 
 @session(tags=["docs", "style"], name="docs(style)")
 def docs_style(session):
+    """
+    Check the documentation style.
+    """
     session.install(
         "doc8",
         "pygments",
@@ -122,6 +143,9 @@ def docs_style(session):
 
 @session(default=False)
 def requirements(session):
+    """
+    Update the project's pinned requirements. Commit the result.
+    """
     session.install("pip-tools")
     for each in [DOCS / "requirements.in", ROOT / "test-requirements.in"]:
         session.run(

pyproject.toml

@@ -70,9 +70,11 @@ ignore = [
 
 [tool.isort]
 combine_as_imports = true
+ensure_newline_before_comments = true
 from_first = true
 include_trailing_comma = true
 multi_line_output = 3
+use_parentheses = true
 
 [tool.pyright]
 strict = ["**/*"]
@@ -122,4 +124,4 @@ docstring-quotes = "double"
 [tool.ruff.per-file-ignores]
 "docs/*" = ["ANN", "D"]
 "referencing/tests/*" = ["ANN", "D", "RUF012"]
-"noxfile.py" = ["ANN", "D"]
+"noxfile.py" = ["ANN", "D100"]