From 8500dbfcd9ef1dfb5492c5fd40f09b53b5e5cae2 Mon Sep 17 00:00:00 2001
From: Stephen Rosen <sirosen@globus.org>
Date: Mon, 19 May 2025 14:35:10 -0400
Subject: [PATCH] Add an example of `pip install --group`

This is another example for the build customization example gallery,
demonstrating how to use `pip` to install from a dependency group.
---
 docs/user/build-customization.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst
index fce8c2bc5fb..347b12ff07c 100644
--- a/docs/user/build-customization.rst
+++ b/docs/user/build-customization.rst
@@ -478,6 +478,32 @@ Take a look at the following example:
 
 MkDocs projects could use ``NO_COLOR=1 uv run mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html`` instead.
 
+Install dependencies from Dependency Groups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python `Dependency Groups <https://packaging.python.org/en/latest/specifications/dependency-groups/>`_
+are a way of storing lists of dependencies in your ``pyproject.toml``.
+
+``pip`` version 25.1 and later, which is the default for Read the Docs builds,
+as well as many other tools support Dependency Groups.
+This example uses ``pip`` and installs from a group named ``docs``:
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+   version: 2
+
+   build:
+      os: ubuntu-24.04
+      tools:
+         python: "3.13"
+      jobs:
+         install:
+            - pip install --group 'docs'
+
+For more information on relevant ``pip`` usage, see the
+`pip user guide on Dependency Groups <https://pip.pypa.io/en/stable/user_guide/#dependency-groups>`_.
+
 Update Conda version
 ~~~~~~~~~~~~~~~~~~~~