Add Sphinx domains for intersphinx consumers

docs/rez_sphinxext.py

@@ -5,6 +5,8 @@
 import rez.cli._main
 import rez.cli._util
 import rez.rezconfig
+from rez.utils.sphinxext import PkgDefDomain as BasePkgDefDomain
+from rez.utils.sphinxext import RexDomain as BaseRexDomain
 import docutils.nodes
 import sphinx.util.nodes
 import sphinx.application
@@ -138,19 +140,13 @@ class BareNamePythonDomain(sphinx.domains.python.PythonDomain):
 
 
 
-class RexDomain(BareNamePythonDomain):
+class RexDomain(BareNamePythonDomain, BaseRexDomain):
     """Domain for rex (Rez EXecution language) objects used in commands() functions."""
 
-    name = "rex"
-    label = "Rex"
 
-
-class PkgDefDomain(BareNamePythonDomain):
+class PkgDefDomain(BareNamePythonDomain, BasePkgDefDomain):
     """Domain for package definition attributes in package.py files."""
 
-    name = "pkgdef"
-    label = "Package Definition"
-
 
 def convert_rez_config_to_rst() -> list[str]:
     with open(rez.rezconfig.__file__) as fd:

docs/source/guides/index.rst

@@ -9,3 +9,4 @@ This section contains various user guides.
 
    update_to_3
    developing_your_own_plugin
+   linking_to_rez_documentation

docs/source/guides/linking_to_rez_documentation.rst

@@ -0,0 +1,67 @@
+============================
+Linking to rez documentation
+============================
+
+Sphinx projects can use `intersphinx <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
+to link to objects in the rez documentation. Rez provides the
+``rez.utils.sphinxext`` Sphinx extension for its two custom domains:
+
+``pkgdef``
+   Package definition attributes and functions documented in
+   :doc:`../package_definition`.
+
+``rex``
+   Objects available to package commands documented in
+   :doc:`../package_commands`.
+
+Configuration
+=============
+
+Install rez and Sphinx in the environment that builds your documentation. Rez
+does not install or pin Sphinx, so your project can select the appropriate Sphinx
+version.
+
+Add the rez extension and intersphinx mapping to your Sphinx ``conf.py`` file:
+
+.. code-block:: python
+
+   extensions = [
+       "sphinx.ext.intersphinx",
+       "rez.utils.sphinxext",
+   ]
+
+   intersphinx_mapping = {
+       "rez": ("https://docs.rez-project.io/en/stable/", None),
+   }
+
+If your project already defines ``extensions`` or ``intersphinx_mapping``, add
+these entries to the existing values instead of replacing them.
+
+Creating links
+==============
+
+Use an explicit external reference to select the rez inventory, domain, and
+object type:
+
+.. code-block:: rst
+
+   :external+rez:pkgdef:attr:`requires`
+   :external+rez:pkgdef:func:`commands`
+   :external+rez:rex:attr:`this.root`
+   :external+rez:rex:func:`alias`
+
+The ``external+rez`` prefix selects the ``rez`` entry in
+``intersphinx_mapping``. The next two components select the domain and role.
+
+Compatibility
+=============
+
+Rez intentionally keeps this integration small and does not install or pin a
+Sphinx version. Documentation projects can select and manage the Sphinx version
+appropriate for their own builds.
+
+We aim to keep ``rez.utils.sphinxext`` compatible across Sphinx and rez releases, but
+not every combination is guaranteed. Changes to Sphinx's domain or intersphinx
+APIs may require an updated rez extension. For reproducible documentation
+builds, projects should pin their documentation dependencies and treat
+unresolved references as errors.

src/rez/utils/sphinxext.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright Contributors to the Rez Project
+
+
+"""Lightweight Sphinx domains for referencing objects in Rez's documentation.
+
+Rez's own documentation adds its directive implementations in ``rez_sphinxext``.
+Consumers only need these domain names and the inherited Python roles for
+intersphinx resolution.
+"""
+
+from rez.utils import _rez_version
+
+from sphinx.domains.python import PythonDomain
+
+__all__ = ["setup"]
+
+
+class RexDomain(PythonDomain):
+    """Domain for Rex objects used in ``commands()`` functions."""
+
+    name = "rex"
+    label = "Rex"
+
+
+class PkgDefDomain(PythonDomain):
+    """Domain for attributes in Rez package definition files."""
+
+    name = "pkgdef"
+    label = "Package Definition"
+
+
+def setup(app):
+    """Register Rez's Sphinx domains."""
+    app.add_domain(RexDomain)
+    app.add_domain(PkgDefDomain)
+
+    return {
+        "version": _rez_version,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }