From 4dd622ad26aa852368b7fe39e74617ee9b03e96f Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Tue, 29 Oct 2024 14:34:44 -0400
Subject: [PATCH] docs: set up docs

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 docs/config.rst   |  7 +++++++
 docs/tutorial.rst |  3 +++
 nox/project.py    | 21 +++++++++++++++++++++
 3 files changed, 31 insertions(+)

diff --git a/docs/config.rst b/docs/config.rst
index 04c0997c..593c1117 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -466,6 +466,13 @@ class.
     :members:
     :undoc-members:
 
+The pyproject.toml helpers
+--------------------------
+
+Nox provides helpers for ``pyproject.toml`` projects in the ``nox.project`` namespace.
+
+.. automodule:: nox.project
+   :members:
 
 Modifying Nox's behavior in the Noxfile
 ---------------------------------------
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index afdfb363..bb4e20e3 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -218,6 +218,9 @@ is provided:
        session.install_and_run_script("peps.py")
 
 
+Other helpers for ``pyproject.toml`` based projects are also available in
+``nox.project``.
+
 Running commands
 ----------------
 
diff --git a/nox/project.py b/nox/project.py
index b0fe7bba..04550d72 100644
--- a/nox/project.py
+++ b/nox/project.py
@@ -41,6 +41,15 @@ def load_toml(filename: os.PathLike[str] | str) -> dict[str, Any]:
     The file must have a ``.toml`` extension to be considered a toml file or a
     ``.py`` extension / no extension to be considered a script. Other file
     extensions are not valid in this function.
+
+    Example:
+
+    .. code-block:: python
+
+        @nox.session
+        def myscript(session):
+            myscript_options = nox.project.load_toml("myscript.py")
+            session.install(*myscript_options["dependencies"])
     """
     filepath = Path(filename)
     if filepath.suffix == ".toml":
@@ -74,5 +83,17 @@ def _load_script_block(filepath: Path) -> dict[str, Any]:
 
 
 def dependency_groups(pyproject: dict[str, Any], *groups: str) -> list[str]:
+    """
+    Get a list of dependencies from a ``[dependency-groups]`` section(s).
+
+    Example:
+
+    .. code-block:: python
+
+        @nox.session
+        def test(session):
+            pyproject = nox.project.load_toml("pyproject.toml")
+            session.install(*nox.project.dependency_groups(pyproject, "dev"))
+    """
     dep_groups = pyproject["dependency-groups"]
     return [item for g in groups for item in resolve(dep_groups, g)]