From b2832cd2435c52a9612838dcc2fc6688d6fa1374 Mon Sep 17 00:00:00 2001
From: Mirza Arnaut <mirza.arnaut45@gmail.com>
Date: Tue, 28 Jul 2026 13:46:20 +0200
Subject: [PATCH] feat: support installing PEP 735 dependency groups from
 pyproject.toml

Adds an opt-in `pyproject_group` input that installs a named
`[dependency-groups]` entry via `pip install --group`, so docs tooling
can be declared as a dev-only group instead of a published package
extra.
---
 README.rst | 39 ++++++++++++++++++++++++++++++++++++++-
 action.yml |  5 +++++
 main.sh    | 11 +++++++++++
 3 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/README.rst b/README.rst
index 9c3a546..9e34e77 100644
--- a/README.rst
+++ b/README.rst
@@ -85,6 +85,8 @@ Input                      Default                      Required Description
                                                                  used in ``pip install -r XXX`` command
 ``pyproject_extras``       ``docs``                     false    Extras of `Requirement Specifier`__
                                                                  used in ``pip install .[XXX]``
+``pyproject_group``                                     false    Dependency group (PEP 735) to install,
+                                                                 used in ``pip install --group XXX``
 ========================== ============================ ======== =================================================
 
 Advanced
@@ -163,7 +165,42 @@ Install extra dependencies
 
 For python dependencies, just add them to your ``requirements.txt`` or ``pyproject.toml`` file.
 
-In your ``pyproject.toml`` file, the extra dependencies must be specified in ``[project.optional-dependencies]``, with the same key as ``pyproject_extras``.
+In your ``pyproject.toml`` file, there are two places to declare the packages needed to build your docs
+(such as Sphinx themes and extensions):
+
+``[project.optional-dependencies]``
+   These are *extras* of your package, meaning they get published as part of your package's metadata
+   and can be installed by your users, e.g. ``pip install yourpkg[docs]``.
+   Use the ``pyproject_extras`` input (default: ``docs``) to select which extra to install, with the
+   same key as used in ``[project.optional-dependencies]``:
+
+   .. code-block:: toml
+
+      [project.optional-dependencies]
+      docs = ["sphinx", "furo"]
+
+``[dependency-groups]``
+   This is the newer `PEP 735`__ mechanism for declaring dev-only dependencies. Unlike extras, groups
+   are **never** seen by the built/published package — the ideal place for docs tooling that has
+   nothing to do with your library's runtime dependencies. Use the ``pyproject_group`` input (default:
+   empty, i.e. disabled) to select which group to install:
+
+   .. code-block:: toml
+
+      [dependency-groups]
+      docs = ["sphinx", "furo"]
+
+   ``pyproject_group`` only accepts a single group name, and requires ``pip >= 25.1`` (the action
+   upgrades pip automatically when this input is set). To combine several groups, compose them inside
+   ``pyproject.toml`` itself using PEP 735's ``include-group``, e.g.:
+
+   .. code-block:: toml
+
+      [dependency-groups]
+      test = ["pytest"]
+      docs = ["sphinx", "furo", {include-group = "test"}]
+
+__ https://peps.python.org/pep-0735/
 
 For non-python dependencies, add a step to your workflow file, and install them with the appropriate tools
 (such as apt, wget, ...). See `#24`__ for example.
diff --git a/action.yml b/action.yml
index 85d6575..6ac1646 100644
--- a/action.yml
+++ b/action.yml
@@ -18,6 +18,10 @@ inputs:
     description: 'Extras of Requirement Specifier, used in `pip install .[XXX]` command'
     required: false
     default: 'docs'
+  pyproject_group:
+    description: 'Dependency group (PEP 735) in pyproject.toml to install, used in `pip install --group XXX` command. Requires pip >= 25.1 (installed automatically when this input is set).'
+    required: false
+    default: ''
   python_version:
     description: 'Version of Python'
     required: false
@@ -96,6 +100,7 @@ runs:
         INPUT_DOCUMENTATION_PATH: ${{ inputs.documentation_path }}
         INPUT_REQUIREMENTS_PATH: ${{ inputs.requirements_path }}
         INPUT_PYPROJECT_EXTRAS: ${{ inputs.pyproject_extras }}
+        INPUT_PYPROJECT_GROUP: ${{ inputs.pyproject_group }}
         INPUT_SPHINX_VERSION: ${{ inputs.sphinx_version }}
         INPUT_CACHE: ${{ inputs.cache }}
         INPUT_SPHINX_BUILD_OPTIONS: ${{ inputs.sphinx_build_options }}
diff --git a/main.sh b/main.sh
index 65e2eb7..5301cbc 100755
--- a/main.sh
+++ b/main.sh
@@ -61,6 +61,17 @@ if [ ! -z "$INPUT_PYPROJECT_EXTRAS" ] ; then
     echo ::endgroup::
 fi
 
+if [ ! -z "$INPUT_PYPROJECT_GROUP" ] ; then
+    echo ::group:: Installing dependency group declared by pyproject.toml[$INPUT_PYPROJECT_GROUP]
+    if [ -f "pyproject.toml" ]; then
+        pip3 install -U 'pip>=25.1'  # --group requires pip 25.1+
+        pip3 install --group "pyproject.toml:$INPUT_PYPROJECT_GROUP"
+    else
+        echo No pyproject.toml found, skipped
+    fi
+    echo ::endgroup::
+fi
+
 echo ::group:: Running Sphinx builder
 build_dir=/tmp/sphinxnotes-pages
 mkdir -p $build_dir || true