matplotlib · ksunden · Jun 26, 2024 · May 23, 2024 · Jun 1, 2024 · timhoffm
diff --git a/doc/api/next_api_changes/development/28289-ES.rst b/doc/api/next_api_changes/development/28289-ES.rst
@@ -0,0 +1,14 @@
+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.
diff --git a/doc/conf.py b/doc/conf.py
@@ -116,9 +116,9 @@ def _parse_skip_subdirs_file():
    'sphinx_gallery.gen_gallery',
    'matplotlib.sphinxext.mathmpl',
    'matplotlib.sphinxext.plot_directive',
+    'matplotlib.sphinxext.roles',
    'matplotlib.sphinxext.figmpl_directive',
    'sphinxcontrib.inkscapeconverter',
-    'sphinxext.custom_roles',
    'sphinxext.github',
    'sphinxext.math_symbol_table',
    'sphinxext.missing_references',

diff --git a/lib/matplotlib/sphinxext/meson.build b/lib/matplotlib/sphinxext/meson.build
@@ -3,6 +3,7 @@ python_sources = [
  'figmpl_directive.py',
  'mathmpl.py',
  'plot_directive.py',
+  'roles.py',
 ]

 typing_sources = [

diff --git a/doc/sphinxext/custom_roles.py → lib/matplotlib/sphinxext/roles.py b/doc/sphinxext/custom_roles.py → lib/matplotlib/sphinxext/roles.py
@@ -2,10 +2,11 @@

 from docutils import nodes

+import matplotlib
 from matplotlib import rcParamsDefault


-class QueryReference(nodes.Inline, nodes.TextElement):
+class _QueryReference(nodes.Inline, nodes.TextElement):
    """
    Wraps a reference or pending reference to add a query string.

@@ -19,7 +20,7 @@
        return '&'.join(f'{name}={value}' for name, value in self.attlist())


-def visit_query_reference_node(self, node):
+def _visit_query_reference_node(self, node):
    """
    Resolve *node* into query strings on its ``reference`` children.

@@ -33,22 +34,22 @@
    self.visit_literal(node)


-def depart_query_reference_node(self, node):
+def _depart_query_reference_node(self, node):
    """
    Act as if this is a `~docutils.nodes.literal`.
    """
    self.depart_literal(node)


-def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+def _rcparam_role(name, rawtext, text, lineno, inliner, options=None, content=None):
    # 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}"]'
    target = 'matplotlibrc-sample'
    ref_nodes, messages = inliner.interpreted(title, f'{title} <{target}>',
                                              'ref', lineno)

-    qr = QueryReference(rawtext, highlight=text)
+    qr = _QueryReference(rawtext, highlight=text)
    qr += ref_nodes
    node_list = [qr]

@@ -64,7 +65,7 @@
    return node_list, messages


-def mpltype_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+def _mpltype_role(name, rawtext, text, lineno, inliner, options=None, content=None):
    mpltype = text
    type_to_link_target = {
        'color': 'colors_def',
@@ -78,12 +79,13 @@


 def setup(app):
-    app.add_role("rc", rcparam_role)
-    app.add_role("mpltype", mpltype_role)
+    app.add_role("rc", _rcparam_role)
+    app.add_role("mpltype", _mpltype_role)
    app.add_node(
-        QueryReference,
-        html=(visit_query_reference_node, depart_query_reference_node),
-        latex=(visit_query_reference_node, depart_query_reference_node),
-        text=(visit_query_reference_node, depart_query_reference_node),
+        _QueryReference,
+        html=(_visit_query_reference_node, _depart_query_reference_node),
+        latex=(_visit_query_reference_node, _depart_query_reference_node),
+        text=(_visit_query_reference_node, _depart_query_reference_node),
    )
-    return {"parallel_read_safe": True, "parallel_write_safe": True}
+    return {"version": matplotlib.__version__,
+            "parallel_read_safe": True, "parallel_write_safe": True}
diff --git a/pyproject.toml b/pyproject.toml
@@ -283,11 +283,11 @@ ignore_directives = [
    "include"
 ]
 ignore_roles = [
-    # sphinxext.custom_roles
-    "rc",
    # matplotlib.sphinxext.mathmpl
    "mathmpl",
    "math-stix",
+    # matplotlib.sphinxext.roles
+    "rc",
    # sphinxext.github
    "ghissue",
    "ghpull",
-Original file line number
+Diff line change
@@ -0,0 +1,14 @@
+    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
             Copy link

  
      
    
  

  
      

  
  Member


      

  

  
    
      

      
            timhoffm
  

      

      

      


        Jun 1, 2024


      
    

  


        
      
  
  
  
    

    There was a problem hiding this comment.


  

 
  
    

    Choose a reason for hiding this comment

    
      The reason will be displayed to describe this comment to others. Learn more.
    

    
      
      


  


  
    
      We can be more explicit here:

explain the problem: roles in inherited docstings
Explicitly write down the exceptions for all our roles („you may see one on the following exceptions). Since we cannot influence the exception messages and they are not telling by themselves, people searching for the message string is their only way forward. We thus should have the stings found in our docs (and that hopefully later also via google).
State that the addition of the extension should be used to solve the inherited docstring issue, but people should not use these roles explicitly in their docs. (Or rather, we don’t give any guarantees on these. - It might still be convenient to use them, but people should be aware that their docs may break in the future and they might have to adapt, which is not the end of the world for doc builds).

    
  
  


    

        
      
  
  
    
  
  
  
    
    Sorry, something went wrong.
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.


  
  


          
      
  
    
    
      
        
            
    All reactions
  


          
          
        
      
    

    



    
        
  
    
        
    
  


      
          
  
      
            Copy link

  
      
    
  

  
      

  
  Member


      

  

  
    
      

      
            timhoffm
  

      

      

      


        Jun 1, 2024


      
    

  


        
      
  
  
  
    

    There was a problem hiding this comment.


  

 
  
    

    Choose a reason for hiding this comment

    
      The reason will be displayed to describe this comment to others. Learn more.
    

    
      
      


  


  
    
      Maybe move the bulk of the explanation to the roles module docstring and give only a very brief summary here, linking to the module docs. That way, it’s easier to update the docs later.
    
  
  


    

        
      
  
  
    
  
  
  
    
    Sorry, something went wrong.
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.


  
  


          
      
  
    
    
            tacaswell reacted with thumbs up emoji
      
        
            
    All reactions
  


          
              
                👍
                  1 reaction
+    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.