Merge branch 'main' into link-focus-visible-style

Author: gabalafou

.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+// container instruction for codespace users
+{
+  "name": "Python 3",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
+  "features": {
+    "ghcr.io/devcontainers-contrib/features/nox:2": {},
+    "ghcr.io/devcontainers-contrib/features/pre-commit:2": {},
+    "ghcr.io/rocker-org/devcontainer-features/pandoc:1": {}
+  },
+  "postCreateCommand": "pre-commit install"
+}

.github/workflows/prerelease.yml

@@ -16,7 +16,7 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4

.github/workflows/publish.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Set up Python 3.9
         uses: actions/setup-python@v4
         with:

.github/workflows/tests.yml

@@ -1,4 +1,7 @@
 name: continuous-integration
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
 
 # README
 # ======
@@ -17,9 +20,6 @@ on:
   pull_request:
   workflow_call:
 
-env:
-  COVERAGE_THRESHOLD: 60
-
 jobs:
   lint:
     strategy:
@@ -28,7 +28,7 @@ jobs:
         python-version: ["3.11"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
@@ -45,19 +45,29 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: ["3.8", "3.9", "3.10", "3.11"]
+        sphinx-version: [""]
         include:
           # macos test
           - os: macos-latest
             python-version: "3.11"
           # windows test
           - os: windows-latest
             python-version: "3.11"
+          # old Sphinx test
+          - os: ubuntu-latest
+            python-version: "3.8"
+            sphinx-version: "old"
+          # dev Sphinx test
+          - os: ubuntu-latest
+            python-version: "3.11"
+            sphinx-version: "dev"
     # needed to cache the browsers for the accessibility tests
     env:
       PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}/pw-browsers
+      SPHINX_VERSION: ${{ matrix.sphinx-version }}
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
@@ -67,34 +77,23 @@ jobs:
       - name: Install dependencies
         # if Sphinx version not specified in matrix, the constraints in the
         # pyproject.toml file determine Sphinx version
-        if: false == matrix.sphinx-version
         shell: bash
         # setting shell to BASH and using PYTHONUTF8 env var makes the editable
         # install work on Windows even though there are emoji in our README
-        run: |
-          export PYTHONUTF8=1
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[test]
-      - name: Install dependencies (legacy Sphinx)
-        # here we override the pyproject.toml constraints to get a specific
-        # Sphinx version.
-        if: matrix.sphinx-version
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[test] sphinx==${{ matrix.sphinx-version }}
+        run: tools/github_actions_install.sh test
       - name: Show installed versions
         run: python -m pip list
       - name: Compile MO files
         run: |
           pip install nox
           nox -s compile
       - name: Run tests
-        run: pytest -m "not a11y" --color=yes --cov pydata_sphinx_theme --cov-branch --cov-report xml:cov.xml --cov-report= --cov-fail-under ${{ env.COVERAGE_THRESHOLD }}
+        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'
-        uses: codecov/codecov-action@v3.1.4
+        uses: codecov/codecov-action@v3
         with:
-          files: cov.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
 
       # note I am setting this on top of the Python cache as I could not find
@@ -122,19 +121,31 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.11"]
+        sphinx-version: [""]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.8"
+            sphinx-version: "old"
+          - os: ubuntu-latest
+            python-version: "3.11"
+            sphinx-version: "dev"
+    env:
+      SPHINX_VERSION: ${{ matrix.sphinx-version }}
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+      # waiting for https://github.com/nikeee/setup-pandoc/pull/8
+      # using 12rambau fork until then
+      - uses: 12rambau/setup-pandoc@test
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[doc]
+        shell: bash
+        run: ./tools/github_actions_install.sh doc
       - name: Show installed versions
         run: python -m pip list
       - name: Build docs
@@ -151,17 +162,16 @@ jobs:
         python-version: ["3.11"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[doc]
+        run: ./tools/github_actions_install.sh doc
+        shell: bash
       - name: Show installed versions
         run: python -m pip list
       # We want to run the audit on a simplified documentation build so that
@@ -195,17 +205,16 @@ jobs:
         python-version: ["3.11"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip wheel setuptools nox
-          python -m pip install -e .[test]
+        run: ./tools/github_actions_install.sh test nox
+        shell: bash
       - name: Show installed versions
         run: python -m pip list
       - name: Generate a profile

.pre-commit-config.yaml

@@ -38,3 +38,8 @@ repos:
     rev: v1.1.1
     hooks:
       - id: doc8
+
+  - repo: "https://github.com/kynan/nbstripout"
+    rev: "0.5.0"
+    hooks:
+      - id: nbstripout

README.md

@@ -41,7 +41,7 @@ And that's it!
 > This theme may not work with the latest major versions of Sphinx, especially
 > if they have only recently been released. Please give us a few months of
 > time to work out any bugs and changes when new releases are made.
-> See [our contributing documentation](docs/community/topics.md) for more information.
+> See [our contributing documentation](https://pydata-sphinx-theme.readthedocs.io/en/stable/community/practices/versions.html#supported-sphinx-versions) for more information.
 
 ## Contribute to and develop the theme
 

docs/_static/custom.css

@@ -41,3 +41,11 @@ div.admonition.admonition-youtube > .admonition-title {
   color: white;
 }
 /* end-custom-youtube */
+
+/* fix for project names that are parsed as links: the whole card is a link so
+ * don't format the project name itself like a text link
+ */
+div.downstream-project-links a {
+  text-decoration: none !important;
+  color: inherit !important;
+}

docs/_static/switcher.json

@@ -4,11 +4,16 @@
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/"
   },
   {
-    "name": "0.13.3 (stable)",
-    "version": "v0.13.3",
+    "name": "0.14.2 (stable)",
+    "version": "v0.14.2",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/",
     "preferred": true
   },
+  {
+    "name": "0.13.3",
+    "version": "v0.13.3",
+    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.13.3/"
+  },
   {
     "name": "0.12.0",
     "version": "v0.12.0",
@@ -23,10 +28,5 @@
     "name": "0.10.1",
     "version": "v0.10.1",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.10.1/"
-  },
-  {
-    "name": "0.9.0",
-    "version": "v0.9.0",
-    "url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.9.0/"
   }
 ]

docs/community/setup.md

@@ -42,6 +42,7 @@ To simplify this process, we use a few helper tools:
 - [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) compiles web assets in an automated way.
 - [pre-commit](https://pre-commit.com/) for automatically enforcing code standards and quality checks before commits.
 - [nox](https://nox.thea.codes/) for automating common development tasks.
+- [pandoc](https://pandoc.org/) the universal document converter.
 
 In particular, `nox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
 The rest of this guide focuses on using `nox` to start with a basic environment.

docs/community/topics/manual-dev.md

@@ -12,30 +12,34 @@ This is optional, but it's best to start with a fresh development environment so
 
 To do so, use a tool like [conda](https://docs.conda.io/en/latest/), [mamba](https://github.com/mamba-org/mamba), or [virtualenv](https://virtualenv.pypa.io/).
 
-## Clone the repository locally
+## Install dependencies
 
-First clone this repository from the `pydata` organization, or from a fork that you have created:
+You must install `sphinx-theme-builder` and Pandoc.
+
+We use the `sphinx-theme-builder` to install `nodejs` locally and to compile all CSS and JS assets needed for the theme.
+Install it like so (note the `cli` option so that we can run it from the command line):
 
 ```console
-$ git clone https://github.com/pydata/pydata-sphinx-theme
-$ cd pydata-sphinx-theme
+$ pip install "sphinx-theme-builder[cli]"
 ```
 
-## Install the `sphinx-theme-builder`
+We use `nbsphinx` to support notebook (.ipynb) files in the documentation, which requires [installing Pandoc](https://pandoc.org/installing.html) at a system level (or within a Conda environment).
 
-We use the `sphinx-theme-builder` to install `nodejs` locally and to compile all CSS and JS assets needed for the theme.
-Install it like so (note the `cli` option so that we can run it from the command line):
+## Clone the repository locally
+
+First clone this repository from the `pydata` organization, or from a fork that you have created:
 
 ```console
-$ pip install sphinx-theme-builder[cli]
+$ git clone https://github.com/pydata/pydata-sphinx-theme
+$ cd pydata-sphinx-theme
 ```
 
 ## Install this theme locally
 
 Next, install this theme locally so that we have the necessary dependencies to build the documentation and testing suite:
 
 ```console
-$ pip install -e .[dev]
+$ pip install -e ".[dev]"
 ```
 
 Note that the `sphinx-theme-builder` will automatically install a local copy of `nodejs` for building the theme's assets.