Document self-referential extras now that pip officially supports it

source/guides/writing-pyproject-toml.rst

@@ -175,6 +175,23 @@ Each of the keys defines a "packaging extra". In the example above, one
 could use, e.g., ``pip install your-project-name[gui]`` to install your
 project with GUI support, adding the PyQt5 dependency.
 
+.. _self-referential-extras:
+
+You can also define an extra that refers back to the same project with
+other extras. This is useful for convenience extras that combine several
+optional features without duplicating their dependency lists:
+
+.. code-block:: toml
+
+   all = ["your-project-name[gui, cli]"]
+
+Installing ``your-project-name[all]`` then installs both the ``gui`` and
+``cli`` dependencies. You can also list extras separately, for example
+``["your-project-name[gui]", "your-project-name[cli]"]``. The name in the
+requirement must match the project's ``name`` field. Installers such as
+:ref:`pip` and :ref:`uv` support this pattern already (pip since
+`version 21.2 <https://pip.pypa.io/en/latest/reference/requirement-specifiers/#self-referential-extras>`_).
+
 
 .. _requires-python:
 .. _python_requires:
@@ -555,6 +572,7 @@ A full example
      "rich",
      "click",
    ]
+   all = ["spam-eggs[gui, cli]"]
 
    [project.urls]
    Homepage = "https://example.com"

source/specifications/pyproject-toml.rst

@@ -498,6 +498,13 @@ marker clause on the related ``Requires-Dist`` entries to check the extra name.
 Optional dependencies are thus only considered for installation if installation
 if the associated extra name is requested.
 
+A dependency specifier in an extra MAY name the project itself with other extras
+(for example, ``all = ["spam[gui, cli]"]``). That way a combined extra does not
+need its own manually maintained copy of each referenced extra's dependencies,
+which can otherwise fall out of sync. Installers that support self-referential
+extras will be able to install the union of these extras' dependencies. See
+:ref:`self-referential extras <self-referential-extras>` for examples.
+
 
 .. _pyproject-toml-import-names: