Document sphinxext.roles

doc/api/index.rst

@@ -126,6 +126,7 @@ Alphabetical list of modules:
    sphinxext_mathmpl_api.rst
    sphinxext_plot_directive_api.rst
    sphinxext_figmpl_directive_api.rst
+   sphinxext_roles.rst
    spines_api.rst
    style_api.rst
    table_api.rst

doc/api/next_api_changes/development/28289-ES.rst

@@ -3,12 +3,5 @@ Documentation-specific custom Sphinx roles are now semi-public
 
 For third-party packages that derive types from Matplotlib, our use of custom roles may
 prevent Sphinx from building their docs. These custom Sphinx roles are now public solely
-for the purposes of use within projects that derive from Matplotlib types, and may be
-added to Sphinx via ``conf.py``::
-
-    extensions = [
-        'matplotlib.sphinxext.roles',
-        # Other extensions.
-    ]
-
-Any other use of these roles is not supported.
+for the purposes of use within projects that derive from Matplotlib types. See
+:mod:`matplotlib.sphinxext.roles` for details.

doc/api/sphinxext_roles.rst

@@ -0,0 +1,7 @@
+==============================
+``matplotlib.sphinxext.roles``
+==============================
+
+.. automodule:: matplotlib.sphinxext.roles
+   :no-undoc-members:
+   :private-members: _rcparam_role, _mpltype_role

lib/matplotlib/sphinxext/roles.py

@@ -1,3 +1,40 @@
+"""
+Custom roles for the Matplotlib documentation.
+
+.. warning::
+
+    These roles are considered semi-public. They are only intended to be used in
+    the Matplotlib documentation.
+
+However, it can happen that downstream packages end up pulling these roles into
+their documentation, which will result in documentation build errors. The following
+describes the exact mechanism and how to fix the errors.
+
+There are two ways, Matplotlib docstrings can end up in downstream documentation.
+You have to subclass a Matplotlib class and either use the ``:inherited-members:``
+option in your autodoc configuration, or you have to override a method without
+specifying a new docstring; the new method will inherit the original docstring and
+still render in your autodoc. If the docstring contains one of the custom sphinx
+roles, you'll see one of the following error messages:
+
+.. code-block:: none
+
+    Unknown interpreted text role "mpltype".
+    Unknown interpreted text role "rc".
+
+To fix this, you can add this module as extension to your sphinx :file:`conf.py`::
+
+    extensions = [
+        'matplotlib.sphinxext.roles',
+        # Other extensions.
+    ]
+
+.. warning::
+
+    Direct use of these roles in other packages is not officially supported. We
+    reserve the right to modify or remove these roles without prior notification.
+"""
+
 from urllib.parse import urlsplit, urlunsplit
 
 from docutils import nodes
@@ -42,6 +79,13 @@ def _depart_query_reference_node(self, node):
 
 
 def _rcparam_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    """
+    Sphinx role ``:rc:`` to highlight and link ``rcParams`` entries.
+
+    Usage: Give the desired ``rcParams`` key as parameter.
+
+    :code:`:rc:`figure.dpi`` will render as: :rc:`figure.dpi`
+    """
     # Generate a pending cross-reference so that Sphinx will ensure this link
     # isn't broken at some point in the future.
     title = f'rcParams["{text}"]'
@@ -66,6 +110,18 @@ def _rcparam_role(name, rawtext, text, lineno, inliner, options=None, content=No
 
 
 def _mpltype_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    """
+    Sphinx role ``:mpltype:`` for custom matplotlib types.
+
+    In Matplotlib, there are a number of type-like concepts that do not have a
+    direct type representation; example: color. This role allows to properly
+    highlight them in the docs and link to their definition.
+
+    Currently supported values:
+
+    - :code:`:mpltype:`color`` will render as: :mpltype:`color`
+
+    """
     mpltype = text
     type_to_link_target = {
         'color': 'colors_def',