[Bug]: mpltype custom role breaks sphinx build for third-party projects that have intersphinx links to matplotlib

[lpsinger]

Bug summary

Sphinx docs builds for third-party packages that have intersphinx cross-references to matplotlib are now failing with the following error message:

Unknown interpreted text role "mpltype".

This is because #27557 and Matplotlib 3.9.0 added the :mpltype: custom role to the docs. Would you please provide some guidance for how packages that depend on Matplotlib should be building their sphinx docs?

Code for reproduction

# See https://git.ligo.org/lscsoft/ligo.skymap

Actual outcome

See https://git.ligo.org/leo-singer/ligo.skymap/-/jobs/3342134

Expected outcome

Build should complete without errors

Additional information

No response

Operating system

No response

Matplotlib Version

3.9.0

Matplotlib Backend

No response

Python version

No response

Jupyter version

No response

Installation

pip

[timhoffm]

As a temporary workaround can you explicitly link against previous matplotlib versions? https://matplotlib.org/3.8.4/objects.inv

Edit: Looking at the error message, I suspect this is not an intersphinx issue. Instead. You are deriving from Matplotlib and by that inherit the docstring from Axes.__init__, which contains the :mpltype: role. As a workaround, you can try to explicitly set a dummy docstring for PPPlot.__init__.

[timhoffm]

TODO: Do we have to make this role publically available via matplotlib.sphinxext so that downstream libraries can include it in their sphinx conf? OTOH :rc: is also not publically available and given its wide use, I'm surpised that nobody has stumbled over that.

[oscargus]

Maybe it makes sense to make it publically available as well as :rc:, so that one can improve the documentation for third-party extensions (especially color would be great).

But isn't the reason for lack of earlier bug reports that very few projects inherit the doc-strings?

[story645]

I don't understand how sphinx registers things well enough, but could it be b/c :rc: is a node object (same with :mathmpl:) while I'm not sure what's going on with :mpltype:

[timhoffm]

There are two ways you can get Sphinx extensions:

1. The docs/sphinxext folder. This is limited to the current docs.
2. Via packages that are added to extensions in conf.py. These are portable and can be reused in other docs.

We currently have :mpltype: in (1), which I believed was enough because it’s intended for internal use only. However, it’s usage can leak into other documentations via docstring inheritance.

There are three ways we can handle this:

1. move the extensions to matplotlib.sphinxext. Affected projects have to include them in their conf.py. To be checked whether the extensions would work in other documentations. Also we’d need to document that these are not intended for general use and can change anytime.
2. Create simpler/dummy extensions in matplotlib.sphinxext that are text-only. Reasonable if 1. does not work or we want to keep the full functionality strictly private.
3. Tell downstream projects, that inherit from us to overwrite docstrings when needed.

I‘m inclined towards (3) because it’s a rare effect and (3) is the least work for us.

[story645]

Via packages that are added to extensions in conf.py. These are portable and can be reused in other docs

Am slightly confused cause we do this in our conf far as I can tell:

matplotlib/doc/conf.py

Line 121 in b63d846

'sphinxext.custom_roles',

[lpsinger]

(3) would mean that projects like mine would need to write dummy Sphinx extensions, right? If so, I would prefer (2).

[tacaswell]

We should promote mpltype to be publicly available.