Skip to main content

Matplotlib theme for Sphinx

Project description

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

A demo of the theme built with the main branch can be seen at https://matplotlib.org/mpl-sphinx-theme/.

When creating a Matplotlib subproject you can include this theme by changing this line in your conf.py file

html_theme = 'mpl_sphinx_theme'

And by including mpl_sphinx_theme as a requirement in your documentation installation.

See the docs/conf.py file for other settings.

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

navbar_center = mpl_nav_bar.html
navbar_end = mpl_icon_links.html

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

To change the top navbar, edit mpl_sphinx_theme/mpl_nav_bar.html

To change the social icons, edit mpl_sphinx_theme/mpl_icon_links.html

To change the style, edit mpl_sphinx_theme/static/css/style.css

Overriding hard coded elements

This theme is primarily designed to be used with subprojects that are part of the main Matplotlib webiste (e.g., [our cheatseets](https://github.com/matplotlib/cheatsheets] and [list of third-party packages](https://github.com/matplotlib/mpl-third-party)). As such several elements are hard coded. However, the theme may also be used by other subprojects that need to change the hard-coded defaults. The following sections explain how to reset these back to their defaults by modifying html_theme_options in conf.py.

Building

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

make html

The built html pages can be found in doc/_build/html/

Releasing

This project uses GitHub Actions to automatically push a new release to PyPI whenever a release is made.

For example, to release a new 3.9.0 version of mpl-sphinx-theme:

  • be sure to edit mpl_sphinx_theme/_version.py

  • checkout the commit you would like to release

  • add a git tag

  • push the tag to the matplotlib/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 required mpl-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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mpl_sphinx_theme-3.9.0.tar.gz (54.5 kB view details)

Uploaded Source

Built Distribution

mpl_sphinx_theme-3.9.0-py3-none-any.whl (53.7 kB view details)

Uploaded Python 3

File details

Details for the file mpl_sphinx_theme-3.9.0.tar.gz.

File metadata

  • Download URL: mpl_sphinx_theme-3.9.0.tar.gz
  • Upload date:
  • Size: 54.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.9

File hashes

Hashes for mpl_sphinx_theme-3.9.0.tar.gz
Algorithm Hash digest
SHA256 439b748361c3f9327cf4114683f8dae4d5bbe810df888973f57096d4d9a9a524
MD5 43a9ef0ea6a049d77f0f211b08c5fb57
BLAKE2b-256 bc74c8cb49a1a863da4e0004d34f0a0071c0408b433fb7160115bc312d63a7da

See more details on using hashes here.

File details

Details for the file mpl_sphinx_theme-3.9.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mpl_sphinx_theme-3.9.0-py3-none-any.whl
Algorithm Hash digest
SHA256 821e2e96823f87519b25578a4212a50c370be623f795a516213c9d7e7cc429ed
MD5 1d04068dcb8ea9913811bf9c422540b1
BLAKE2b-256 8fef824dc2e2fec88f98b5803bd4fb273816180307dbdbb9c36cfa01e0128f32

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page