diff --git a/.circleci/config.yml b/.circleci/config.yml index dcf06ca..3231e38 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -2,11 +2,13 @@ version: 2.1 orbs: - python: circleci/python@1.2.1 + python: circleci/python@3.2.0 jobs: build_docs: - executor: python/default + executor: + name: python/default + tag: "3.11" steps: - checkout - python/install-packages: diff --git a/.github/.github/workflows/lighthouse.yml b/.github/.github/workflows/lighthouse.yml index a766f75..119ca82 100644 --- a/.github/.github/workflows/lighthouse.yml +++ b/.github/.github/workflows/lighthouse.yml @@ -1,10 +1,14 @@ name: Lighthouse +permissions: + contents: read on: [push, pull_request] jobs: CI: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 + with: + persist-credentials: false - name: Set up Python 3.7 uses: actions/setup-python@v1 @@ -22,7 +26,7 @@ jobs: make html - name: Run Lighthouse against example docs build - uses: treosh/lighthouse-ci-action@v2 + uses: treosh/lighthouse-ci-action@005e1277a8a17ea0b0ef6c3332d59a7cd0f730ce # v2 with: configPath: "./lighthouserc.json" temporaryPublicStorage: true diff --git a/.github/.github/workflows/pre-commit.yaml b/.github/.github/workflows/pre-commit.yaml index 82e8821..3370c9b 100644 --- a/.github/.github/workflows/pre-commit.yaml +++ b/.github/.github/workflows/pre-commit.yaml @@ -1,4 +1,6 @@ name: Linting +permissions: + contents: read on: push: @@ -12,5 +14,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 + with: + persist-credentials: false - uses: actions/setup-python@v2 - - uses: pre-commit/action@v2.0.0 + - uses: pre-commit/action@0764670bf370aab253130d534e1eda7ff497dc60 # v2.0.0 diff --git a/.github/.github/workflows/publish-pypi.yml b/.github/.github/workflows/publish-pypi.yml index 78cbfe6..1009f57 100644 --- a/.github/.github/workflows/publish-pypi.yml +++ b/.github/.github/workflows/publish-pypi.yml @@ -1,4 +1,6 @@ name: Push to PyPI +permissions: + contents: read on: push: @@ -8,10 +10,15 @@ on: jobs: publish: runs-on: ubuntu-latest - + permissions: + id-token: write + attestations: write + contents: read steps: - name: Checkout uses: actions/checkout@v1 + with: + persist-credentials: false - name: Set up Python 3.7 uses: actions/setup-python@v1 @@ -29,7 +36,7 @@ jobs: python setup.py sdist bdist_wheel - name: Publish mpl-sphinx-theme - uses: pypa/gh-action-pypi-publish@master + uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4 with: user: __token__ password: ${{ secrets.pypi_token }} diff --git a/.github/.githubold/workflows/main.yml b/.github/.githubold/workflows/main.yml index c6864b5..94d61c5 100644 --- a/.github/.githubold/workflows/main.yml +++ b/.github/.githubold/workflows/main.yml @@ -5,7 +5,7 @@ jobs: name: Run CircleCI artifacts redirector steps: - name: GitHub Action step - uses: larsoner/circleci-artifacts-redirector-action@master + uses: scientific-python/circleci-artifacts-redirector-action@7eafdb60666f57706a5525a2f5eb76224dc8779b # v1.1.0 with: repo-token: ${{ secrets.GITHUB_TOKEN }} artifact-path: 0/docs/_build/html/index.html diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f9086b3 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,20 @@ +--- +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + groups: + actions: + patterns: + - "*" + + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + groups: + python: + patterns: + - "*" diff --git a/.github/workflows/circleci.yml b/.github/workflows/circleci.yml index 481368d..226ceb4 100644 --- a/.github/workflows/circleci.yml +++ b/.github/workflows/circleci.yml @@ -10,7 +10,8 @@ jobs: name: Run CircleCI artifacts redirector steps: - name: GitHub Action step - uses: larsoner/circleci-artifacts-redirector-action@master + uses: + scientific-python/circleci-artifacts-redirector-action@839631420e45a08af893032e5a5e8843bf47e8ff # v1.2.0 with: repo-token: ${{ secrets.GITHUB_TOKEN }} api-token: ${{ secrets.CIRCLECI_TOKEN }} diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index f3866b4..97d80dc 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -3,28 +3,30 @@ name: Linting on: [pull_request] +permissions: + contents: read + jobs: flake8: name: flake8 runs-on: ubuntu-latest + permissions: + checks: write steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + with: + persist-credentials: false - name: Set up Python 3 - uses: actions/setup-python@v1 + uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0 with: - python-version: 3.8 + python-version: '3.x' - name: Install flake8 run: pip3 install 'flake8>=3.8' - name: Set up reviewdog - run: | - mkdir -p "$HOME/bin" - curl -sfL \ - https://github.com/reviewdog/reviewdog/raw/master/install.sh | \ - sh -s -- -b "$HOME/bin" - echo "$HOME/bin" >> $GITHUB_PATH + uses: reviewdog/action-setup@d8edfce3dd5e1ec6978745e801f9c50b5ef80252 # v1.4.0 - name: Run flake8 env: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 88954a9..9761836 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -6,20 +6,24 @@ on: types: - published +permissions: + contents: read + jobs: build: name: Build Release Packages runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 with: - fetch-depth: 10 + fetch-depth: 0 + persist-credentials: false - name: Set up Python id: setup - uses: actions/setup-python@v4 + uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0 with: - python-version: 3.x + python-version: '3.x' - name: Install build tools run: | @@ -30,7 +34,7 @@ jobs: run: python -m build - name: Save built packages as artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 with: name: packages-${{ runner.os }}-${{ steps.setup.outputs.python-version }} path: dist/ @@ -43,15 +47,16 @@ jobs: runs-on: ubuntu-latest environment: release permissions: + attestations: write + contents: read id-token: write steps: - name: Download packages - uses: actions/download-artifact@v3 - - - name: Consolidate packages for upload - run: | - mkdir dist - cp packages-*/* dist/ + uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0 + with: + pattern: packages-* + path: dist + merge-multiple: true - name: Publish package distributions to PyPI - uses: pypa/gh-action-pypi-publish@b7f401de30cb6434a1e19f805ff006643653240e # v1.8.10 + uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0 diff --git a/.gitignore b/.gitignore index bacf9c1..2d088b1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ /mpl_sphinx_theme.egg-info/ /mpl_sphinx_theme/__pycache__/ build +dist \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..6361358 --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +# 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. + +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 + +```python +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`. + +### 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 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`: + +- 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 + +```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](https://github.com/matplotlib/mpl-sphinx-theme/releases/new). + +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 diff --git a/README.rst b/README.rst deleted file mode 100644 index 663fc19..0000000 --- a/README.rst +++ /dev/null @@ -1,92 +0,0 @@ -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. - -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 - -.. code-block:: python - - 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``: - -.. code-block:: - - 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``. - -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 - -.. code-block:: - - 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 - -.. code-block:: - - $ 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 -`_. - -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 diff --git a/docs/conf.py b/docs/conf.py index e148716..18b8e08 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,7 +29,8 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'matplotlib.sphinxext.plot_directive', + "matplotlib.sphinxext.plot_directive", + "sphinx_design" ] # Add any paths that contain templates here, relative to this directory. @@ -61,6 +62,12 @@ "navbar_links": "absolute", } +html_sidebars = { + "index": [ + "donate_sidebar.html", + ], +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/mpl_sphinx_theme/_version.py b/mpl_sphinx_theme/_version.py index 10ddec0..5dbb30c 100644 --- a/mpl_sphinx_theme/_version.py +++ b/mpl_sphinx_theme/_version.py @@ -4,5 +4,5 @@ # Copyright (c) Matplotlib developers. # Distributed under the terms of the Modified BSD License. -version_info = (3, 9, 0) -__version__ = ".".join(map(str, version_info)) +version_info = (3, 9, 1) +__version__ = ".".join(map(str, version_info)) + "dev0" diff --git a/mpl_sphinx_theme/donate_sidebar.html b/mpl_sphinx_theme/donate_sidebar.html index a4a0777..9744abe 100644 --- a/mpl_sphinx_theme/donate_sidebar.html +++ b/mpl_sphinx_theme/donate_sidebar.html @@ -1,8 +1,5 @@ - - -
- - Support Matplotlib - -
+ + Support Matplotlib + + diff --git a/mpl_sphinx_theme/mpl_icon_links.html b/mpl_sphinx_theme/mpl_icon_links.html index 964a333..12edba2 100644 --- a/mpl_sphinx_theme/mpl_icon_links.html +++ b/mpl_sphinx_theme/mpl_icon_links.html @@ -3,7 +3,6 @@ { "url": "https://gitter.im/matplotlib/matplotlib", "icon": "fa-brands fa-gitter", "name": "Gitter" }, { "url": "https://discourse.matplotlib.org", "icon": "fa-brands fa-discourse", "name": "Discourse" }, { "url": "https://github.com/matplotlib/matplotlib", "icon": "fa-brands fa-github", "name": "GitHub" }, - { "url": "https://twitter.com/matplotlib/", "icon": "fa-brands fa-twitter", "name": "Twitter" }, ] -%} {%- endif -%} {% extends "navbar-icon-links.html" %} diff --git a/mpl_sphinx_theme/static/css/style.css b/mpl_sphinx_theme/static/css/style.css index 4284099..f307818 100644 --- a/mpl_sphinx_theme/static/css/style.css +++ b/mpl_sphinx_theme/static/css/style.css @@ -14,15 +14,15 @@ html[data-theme="dark"] { } :root { ---pst-color-link-hover: var(--pst-color-secondary); + --pst-color-link-hover: var(--pst-color-secondary); } -.sidebar-cheatsheets, .sidebar-donate { - margin: 2.75rem 0; +.sidebar-donate > .sd-btn { + width: 100%; } #navbar-icon-links { - margin-left: 1.5em; + margin-left: 1.5em; } #navbar-icon-links .nav-link { @@ -33,3 +33,10 @@ html[data-theme="dark"] { color: var(--pst-color-primary); } +/* reduce height of nav bar when items don't fit in one line + See https://github.com/pydata/pydata-sphinx-theme/pull/2117 + */ +.navbar-item { + height: unset !important; + margin: 0.25rem 0; +} \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 55a2847..e1c3ae2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,8 +19,9 @@ classifiers = [ "Topic :: Documentation :: Sphinx", ] dependencies = [ - "pydata-sphinx-theme>=0.13.1", + "pydata-sphinx-theme==0.16.1", "matplotlib", + "sphinx-design", ] [project.urls]