matplotlib.sphinxext.roles#

Custom roles for the Matplotlib documentation.

Warning

These roles are considered semi-public. They are only intended to be used inthe Matplotlib documentation.

However, it can happen that downstream packages end up pulling these roles intotheir documentation, which will result in documentation build errors. The followingdescribes 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 withoutspecifying a new docstring; the new method will inherit the original docstring andstill render in your autodoc. If the docstring contains one of the custom sphinxroles, you'll see one of the following error messages:

Unknown interpreted text role "mpltype".Unknown interpreted text role "rc".

To fix this, you can add this module as extension to your sphinxconf.py:

extensions=['matplotlib.sphinxext.roles',# Other extensions.]

Warning

Direct use of these roles in other packages is not officially supported. Wereserve the right to modify or remove these roles without prior notification.

matplotlib.sphinxext.roles._mpltype_role(name,rawtext,text,lineno,inliner,options=None,content=None)[source]#

Sphinx role:mpltype: for custom matplotlib types.

In Matplotlib, there are a number of type-like concepts that do not have adirect type representation; example: color. This role allows to properlyhighlight them in the docs and link to their definition.

Currently supported values:

  • :mpltype:`color` will render as:color

matplotlib.sphinxext.roles._rcparam_role(name,rawtext,text,lineno,inliner,options=None,content=None)[source]#

Sphinx role:rc: to highlight and linkrcParams entries.

Usage: Give the desiredrcParams key as parameter.

:rc:`figure.dpi` will render as:rcParams["figure.dpi"] (default:100.0)