From 468e7f95c0a6ab81693587eaf891488ec51f7b5b Mon Sep 17 00:00:00 2001 From: David Stansby Date: Sun, 23 Mar 2025 14:11:29 +0000 Subject: [PATCH 1/2] Cleanup README --- README.rst => README.md | 67 +++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 36 deletions(-) rename README.rst => README.md (68%) diff --git a/README.rst b/README.md similarity index 68% rename from README.rst rename to README.md index 663fc19..b5a4f96 100644 --- a/README.rst +++ b/README.md @@ -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. @@ -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 -.. 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. @@ -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``. @@ -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 -`_ +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``: @@ -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 - $ git tag -s -a v3.9.0 -m 'REL: 3.9.0' - $ git push upstream --tags +```sh +git checkout +git tag -s -a v3.9.0 -m 'REL: 3.9.0' +git push upstream --tags +``` -Finally, `turn the tag into a GitHub release -`_. +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 From ef7aed51b0a8841cf6b6433a272bd23df62ad86a Mon Sep 17 00:00:00 2001 From: David Stansby Date: Tue, 25 Mar 2025 09:41:39 +0000 Subject: [PATCH 2/2] Clean up double backticks --- README.md | 47 ++++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index b5a4f96..6361358 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,39 @@ # 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. +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 +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 +line in your `conf.py` file ```python html_theme = 'mpl_sphinx_theme' ``` -And by including ``mpl_sphinx_theme`` as a requirement in your documentation +And by including `mpl_sphinx_theme` as a requirement in your documentation installation. -See the ``docs/conf.py`` file for other settings. +See the `docs/conf.py` file for other settings. -There are two main templates that replace the defaults in ``pydata-sphinx-theme``: +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``. +`mpl_sphinx_theme/static/logo_{light,dark}.svg`. -To change the top navbar, edit ``mpl_sphinx_theme/mpl_nav_bar.html`` +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 social icons, edit `mpl_sphinx_theme/mpl_icon_links.html` -To change the style, edit ``mpl_sphinx_theme/static/css/style.css`` +To change the style, edit `mpl_sphinx_theme/static/css/style.css` ## Overriding hard coded elements @@ -42,33 +43,33 @@ 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``. +`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``. +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 +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/`` +The built html pages can be found in `doc/_build/html/` ## Releasing 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``: +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 +- push the tag to the `matplotlib/mpl-sphinx-theme` repository ```sh git checkout @@ -78,10 +79,10 @@ git push upstream --tags 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: +Update the required `mpl-sphinx-theme` version in the following files: -* [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 +- [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