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.htmlNote 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.
Header section links
Use a copy of [the default pydata-sphinx-theme navbar](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-nav.html) and set the 'navbar_center' key to this HTML file in html_theme_options.
Building
To build the theme with a sample page, navigate into the doc/ directory and run
make htmlThe 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 --tagsFinally, 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 439b748361c3f9327cf4114683f8dae4d5bbe810df888973f57096d4d9a9a524 |
|
| MD5 | 43a9ef0ea6a049d77f0f211b08c5fb57 |
|
| BLAKE2b-256 | bc74c8cb49a1a863da4e0004d34f0a0071c0408b433fb7160115bc312d63a7da |
Provenance
File details
Details for the file mpl_sphinx_theme-3.9.0-py3-none-any.whl.
File metadata
- Download URL: mpl_sphinx_theme-3.9.0-py3-none-any.whl
- Upload date:
- Size: 53.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/4.0.2 CPython/3.11.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 821e2e96823f87519b25578a4212a50c370be623f795a516213c9d7e7cc429ed |
|
| MD5 | 1d04068dcb8ea9913811bf9c422540b1 |
|
| BLAKE2b-256 | 8fef824dc2e2fec88f98b5803bd4fb273816180307dbdbb9c36cfa01e0128f32 |
