Repository files navigation

This is the official Sphinx theme for Matplotlib documentation. It extends thepydata-sphinx-theme project, but adds custom styling and a navigation bar.

A demo of the theme built with themain branch can be seen athttps://matplotlib.org/mpl-sphinx-theme/.

When creating a Matplotlib subproject you can include this theme by changing thisline in yourconf.py file

html_theme='mpl_sphinx_theme'

And by includingmpl_sphinx_theme as a requirement in your documentationinstallation.

See thedocs/conf.py file for other settings.

There are two main templates that replace the defaults inpydata-sphinx-theme:

navbar_center = mpl_nav_bar.htmlnavbar_end = mpl_icon_links.html

Note that the logo options need not be specified as they are included in themeinitialization. The logo is stored atmpl_sphinx_theme/static/logo_{light,dark}.svg.

To change the top navbar, editmpl_sphinx_theme/mpl_nav_bar.html

To change the social icons, editmpl_sphinx_theme/mpl_icon_links.html

To change the style, editmpl_sphinx_theme/static/css/style.css

This theme is primarily designed to be used with subprojects that are part of the mainMatplotlib webiste (e.g.,our cheatseetsandlist of third-party packages).As such several elements are hard coded. However, the theme may also be used byother subprojects that need to change the hard-coded defaults.The following sections explain how to reset these back to their defaults by modifyinghtml_theme_options inconf.py.

Use a copy ofthe default pydata-sphinx-theme navbar and set the'navbar_center' key to this HTML file inhtml_theme_options.

To build the theme with a sample page, navigate into thedoc/ directory and run

make html

The built html pages can be found indoc/_build/html/

This projectuses GitHub Actionsto automatically push a new release to PyPI whenever a release is made.

For example, to release a new3.9.0 version ofmpl-sphinx-theme:

• be sure to editmpl_sphinx_theme/_version.py
• checkout the commit you would like to release
• add a git tag
• push the tag to thematplotlib/mpl-sphinx-theme repository

git checkout<commit-hash>git tag -s -a v3.9.0 -m'REL: 3.9.0'git push upstream --tags

Finally,turn the tag into a GitHub release.

Update the requiredmpl-sphinx-theme version in the following files:

• matplotlib/matplotlib: requirements/doc/doc-requirements.txt
• matplotlib/mpl-brochure-site: requirements.txt
• matplotlib/mpl-third-party: docs/requirements.txt
• matplotlib/governance: requirements-doc.txt
• matplotlib/mpl-gui: requirements-doc.txt