Skip to content

Cleanup README #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 25, 2025
Merged

Cleanup README #98

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
468e7f9
Cleanup README
dstansby Mar 23, 2025
ef7aed5
Clean up double backticks
dstansby Mar 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 31 additions & 36 deletions README.rst → README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Matplotlib Sphinx Theme
=======================
# Matplotlib Sphinx Theme

This is the official Sphinx theme for Matplotlib documentation. It extends the
``pydata-sphinx-theme`` project, but adds custom styling and a navigation bar.
Expand All @@ -10,9 +9,9 @@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't all double backticks changed to single backticks?

Copy link
Member Author

@dstansby dstansby Mar 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching - annoyingly that makes enough changes that there isn't a nice overall diff, but looking at the diff of the two commits individually still seems to work to easily see what's changed.


.. code-block:: python

html_theme = 'mpl_sphinx_theme'
```python
html_theme = 'mpl_sphinx_theme'
```

And by including ``mpl_sphinx_theme`` as a requirement in your documentation
installation.
Expand All @@ -21,11 +20,10 @@ See the ``docs/conf.py`` file for other settings.

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

.. code-block::

navbar_center = mpl_nav_bar.html
navbar_end = mpl_icon_links.html

```
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``.
Expand All @@ -36,35 +34,33 @@ 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
------------------------------
## 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]
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
~~~~~~~~~~~~~~~~~~~~
### 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
## Building

.. code-block::
To build the theme with a sample page, navigate into the ``doc/`` directory and run

make html
```
make html
```

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

Releasing
---------
## Releasing

This project `uses GitHub Actions
<https://github.com/matplotlib/mpl-sphinx-theme/blob/main/.github/workflows/release.yml>`_
This project [uses GitHub Actions](https://github.com/matplotlib/mpl-sphinx-theme/blob/main/.github/workflows/release.yml)
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``:
Expand All @@ -74,19 +70,18 @@ For example, to release a new ``3.9.0`` version of ``mpl-sphinx-theme``:
- add a git tag
- push the tag to the ``matplotlib/mpl-sphinx-theme`` repository

.. code-block::

$ git checkout <commit-hash>
$ git tag -s -a v3.9.0 -m 'REL: 3.9.0'
$ git push upstream --tags
```sh
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
<https://github.com/matplotlib/mpl-sphinx-theme/releases/new>`_.
Finally, [turn the tag into a GitHub release](https://github.com/matplotlib/mpl-sphinx-theme/releases/new).

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
* [matplotlib/matplotlib](https://github.com/matplotlib/matplotlib): requirements/doc/doc-requirements.txt
* [matplotlib/mpl-brochure-site](https://github.com/matplotlib/mpl-brochure-site): requirements.txt
* [matplotlib/mpl-third-party](https://github.com/matplotlib/mpl-third-party): docs/requirements.txt
* [matplotlib/governance](https://github.com/matplotlib/governance): requirements-doc.txt
* [matplotlib/mpl-gui](https://github.com/matplotlib/mpl-gui): requirements-doc.txt