Merge main into feature-focus

.github/dependabot.yml

@@ -1,8 +1,19 @@
 version: 2
 updates:
-  # Maintain dependencies for GitHub Actions
+  # GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      # Check for updates to GitHub Actions every week
       interval: "weekly"
+    labels:
+      - "tag: dependencies"
+      - "tag: CI"
+  # npm
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "tag: dependencies"
+      - "tag: javascript"
+    open-pull-requests-limit: 0 # security updates only

.github/workflows/prerelease.yml

@@ -13,13 +13,13 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"

.github/workflows/publish.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Checkout source
         uses: actions/checkout@v4
       - name: Set up Python 3.9
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.9"
       - name: Install gettext for translations

.github/workflows/tests.yml

@@ -25,12 +25,12 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.11"]
+        python-version: ["3.12"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -44,22 +44,22 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
         sphinx-version: [""]
         include:
           # macos test
           - os: macos-latest
-            python-version: "3.11"
+            python-version: "3.12"
           # windows test
           - os: windows-latest
-            python-version: "3.11"
+            python-version: "3.12"
           # old Sphinx test
           - os: ubuntu-latest
-            python-version: "3.8"
+            python-version: "3.9"
             sphinx-version: "old"
           # dev Sphinx test
           - os: ubuntu-latest
-            python-version: "3.11"
+            python-version: "3.12"
             sphinx-version: "dev"
     # needed to cache the browsers for the accessibility tests
     env:
@@ -69,7 +69,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -93,7 +93,7 @@ jobs:
       - name: Run tests
         run: pytest -m "not a11y" --color=yes --cov --cov-report=xml
       - name: Upload to Codecov
-        if: matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest'
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v3
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -102,7 +102,7 @@ jobs:
       # note I am setting this on top of the Python cache as I could not find
       # how to set the hash key on the python one
       - name: Set up browser cache (for accessibility tests)
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ${{ github.workspace }}/pw-browsers
@@ -111,7 +111,7 @@ jobs:
             ${{ runner.os }}-pw-
 
       - name: Run accessibility tests with playwright
-        if: matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest'
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
         run: |
           nox -s a11y
         continue-on-error: true
@@ -123,15 +123,17 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.11"]
+        python-version: ["3.12"]
         sphinx-version: [""]
         include:
           - os: ubuntu-latest
-            python-version: "3.8"
+            python-version: "3.9"
             sphinx-version: "old"
-          - os: ubuntu-latest
-            python-version: "3.11"
-            sphinx-version: "dev"
+          # crash with myst parser
+          # will be restored when myst will be dropped from our documentation
+          # - os: ubuntu-latest
+          #   python-version: "3.12"
+          #   sphinx-version: "dev"
     env:
       SPHINX_VERSION: ${{ matrix.sphinx-version }}
     runs-on: ${{ matrix.os }}
@@ -141,7 +143,7 @@ jobs:
       # using 12rambau fork until then
       - uses: 12rambau/setup-pandoc@test
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -162,12 +164,12 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.11"]
+        python-version: ["3.12"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -205,12 +207,12 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.11"]
+        python-version: ["3.12"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -223,7 +225,7 @@ jobs:
       - name: Generate a profile
         run: nox -s profile
         continue-on-error: true
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: profile-results
           path: profile.svg

.pre-commit-config.yaml

@@ -9,8 +9,9 @@ repos:
     hooks:
       - id: prettier
         # Exclude the HTML, since it doesn't understand Jinja2
-        # exclude also the webpack.congo.js file has it embed complete url dificult to prettify
-        exclude: .+\.html|webpack\.config\.js
+        # exclude also the webpack.config.js file has it embed complete url dificult to prettify
+        # exclude the pytest-regressions folder tests/test_ally
+        exclude: .+\.html|webpack\.config\.js|tests/test_a11y/
 
   - repo: https://github.com/psf/black
     rev: 22.12.0

RELEASE.md

@@ -0,0 +1,36 @@
+# Release instructions
+
+This page contains the steps to make a release and some helpful resources to get you started.
+
+Create an issue and copy/paste the steps below to release a new version. Close the issue when it is done.
+
+These steps should be taken in order to create a new release![^release-refs]
+
+```md
+**Double check for quality-control**
+
+- [ ] There are no [open issues with a `impact: block-release` label](https://github.com/pydata/pydata-sphinx-theme/labels/impact%3A%20block-release)
+
+**Prepare the codebase for a new version**
+
+- [ ] Bump `__version__` in [`__init__.py`](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/__init__.py#L16)
+- [ ] Update our [version switcher `.json` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/_static/switcher.json) with the new version
+- [ ] Make a release commit: `git commit -m 'bump: 0.1.9 → 0.2.0'`
+- [ ] Push the RLS commit `git push upstream main`
+- [ ] If a **release candidate** is needed, tick this box when we're now ready for a full release.
+
+**Make the release**
+
+- [ ] [Start a new GitHub release](https://github.com/pandas-dev/pydata-sphinx-theme/releases/new)
+  - Call the release the current version, e.g. `v0.2.0`
+  - In the **`Choose a Tag:`** dropdown, type in the release name (e.g., `v0.2.0`) and click "Create new tag"
+  - In the **`Target:`** dropdown, pin it to the release commit that you've just pushed.
+  - Generate the automatic release notes, eventually manually specify the previous version (useful when several release candidate have been made)
+- [ ] Confirm that the release completed
+  - [The `publish` github action job](https://github.com/pydata/pydata-sphinx-theme/blob/main/.github/workflows/publish.yml#L31) has completed successfully in the [actions tab](https://github.com/pydata/pydata-sphinx-theme/actions).
+  - [The PyPI version is updated](https://pypi.org/project/pydata-sphinx-theme/)
+- [ ] Hide the previous patch version build in the RDT interface if needed.
+- [ ] Celebrate, you're done!
+
+[^release-refs]: Taken from [the release checklist](https://github.com/pydata/pydata-sphinx-theme/blob/main/RELEASE.md). See [the release documentation](https://pydata-sphinx-theme.readthedocs.io/en/latest/contribute/policies.html#release-policy) for an overview of release processes.
+```

docs/_static/gallery.yaml

@@ -11,6 +11,9 @@
 - title: Bokeh
   link: https://docs.bokeh.org/en/latest/
   img-bottom: ../_static/gallery/bokeh.png
+- title: Brightway
+  link: https://docs.brightway.dev/en/latest/
+  img-bottom: ../_static/gallery/brightway.png
 - title: Jupyter
   link: https://docs.jupyter.org/en/latest/
   img-bottom: ../_static/gallery/jupyter.png

docs/_static/switcher.json

@@ -4,11 +4,16 @@
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/"
   },
   {
-    "name": "0.14.4 (stable)",
-    "version": "v0.14.4",
+    "name": "0.15.2 (stable)",
+    "version": "v0.15.2",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/",
     "preferred": true
   },
+  {
+    "name": "0.14.4",
+    "version": "v0.14.4",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.14.4/"
+  },
   {
     "name": "0.13.3",
     "version": "v0.13.3",
@@ -23,10 +28,5 @@
     "name": "0.11.0",
     "version": "v0.11.0",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.11.0/"
-  },
-  {
-    "name": "0.10.1",
-    "version": "v0.10.1",
-    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.10.1/"
   }
 ]

docs/community/practices/release.md

@@ -19,7 +19,7 @@ Anybody is encouraged to make a new release if:
 
 - It has been more than a month since the last release.
 - OR a significant change has been made to our code that warrants a release.
-- AND there are no open issues with a [{guilabel}`block-release`](https://github.com/pydata/pydata-sphinx-theme/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ablock-release) label.
+- AND there are no open issues with a [{guilabel}`impact: block-release`](https://github.com/pydata/pydata-sphinx-theme/labels/impact%3A%20block-release) label.
 
 ### Release candidates
 
@@ -35,7 +35,7 @@ Follow these steps to make a release:
 
 - (optionally) **Create a [GitHub milestones](https://github.com/pydata/pydata-sphinx-theme/milestones)** to organize the issues that should be resolved as part of a new release.
 - **Decide if it's time** to make a release be reading [](releases:when) and decide if it is time for a release.
-- **Copy the release checklist into a new issue**. We have [a release checklist in our wiki](https://github.com/pydata/pydata-sphinx-theme/wiki/Release-checklist#release-instructions).
+- **Copy the [release checklist](https://github.com/pydata/pydata-sphinx-theme/blob/main/RELEASE.md) into a new issue**.
 - **Complete the checklist**. That's it!
 
 ## Choosing a version increment

docs/community/topics/bootstrap.rst

@@ -60,3 +60,4 @@ JavaScript
 ^^^^^^^^^^
 
 -   Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.
+-   Bootstrap's `Programmatic API <https://getbootstrap.com/docs/5.0/getting-started/javascript/#programmatic-api>`_, ``bootstrap``, is also available. This API can be useful for initializing opt-in components that are not initialized by default such as `Popovers <https://getbootstrap.com/docs/5.0/components/popovers/#overview>`_.

docs/conf.py

@@ -184,12 +184,16 @@
     # "content_footer_items": ["test", "test"],
     "footer_start": ["copyright"],
     "footer_center": ["sphinx-version"],
-    # "secondary_sidebar_items": ["page-toc"],  # Remove the source buttons
+    "secondary_sidebar_items": {
+        "**/*": ["page-toc", "edit-this-page", "sourcelink"],
+        "examples/no-sidebar": [],
+    },
     "switcher": {
         "json_url": json_url,
         "version_match": version_match,
     },
     "navigation_with_keys": False,
+    # "back_to_top_button": False,
     # "search_bar_position": "navbar",  # TODO: Deprecated - remove in future version
 }
 

docs/examples/gallery.md

@@ -25,8 +25,6 @@ Thanks for your support!
 
 - title: Binder
   link: https://mybinder.readthedocs.io/en/latest/index.html
-- title: Brightway
-  link: https://docs.brightway.dev/en/latest/
 - title: cashocs
   link: https://cashocs.readthedocs.io/en/stable/
 - title: CuPy

docs/examples/in-page-toc.rst

@@ -0,0 +1,49 @@
+:html_theme.sidebar_secondary.remove: true
+
+Test of in-page TOC with no right sidebar
+=========================================
+
+This page tests that the local contents directive looks okay.
+
+.. attention::
+
+    We **do not recommend** using this directive on pages that use this theme
+    because PyData Theme provides an in-page table of contents in the right sidebar
+    by default.
+
+If you do choose to use an inline, in-page table of contents, we recommend that
+you turn off the right sidebar as follows.
+
+.. contents:: Page contents
+    :local:
+
+
+Add a local table of contents (in-page)
+---------------------------------------
+
+Add the local table of contents directive near the top of your ``.rst`` page:
+
+.. code-block:: rst
+
+    .. contents:: Page contents
+        :local:
+
+This directive will generate a table of contents for the section where this was
+added, as shown on this page.
+
+
+Turn off the right sidebar for a single page
+--------------------------------------------
+
+On the very top line of your ``.rst`` file, insert the following line:
+
+.. code-block:: rst
+
+    :html_theme.sidebar_secondary.remove: true
+
+This will render the page without the right sidebar, also known as the secondary
+sidebar, which contains the table of contents for that page.
+
+Be aware that if you remove the sidebar you may also remove the "Edit on ..."
+and "Show source" links for that page, since by default those are configured for
+the right sidebar.

docs/examples/index.rst

@@ -29,6 +29,7 @@ See the sections in the primary sidebar and below to explore.
 
     no-sidebar
     persistent-search-field
+    in-page-toc
     subpages/index
     mult_headers
     Link to an external site <https://jupyterbook.org/>