update branch

.github/workflows/prerelease.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Install (prerelease) dependencies
         run: |
           python -m pip install --upgrade pip wheel setuptools
-          python -m pip install --upgrade --pre -e .[test]
+          python -m pip install --upgrade --pre -e .[doc,test]
 
       - name: Build docs to store
         run: |

.github/workflows/publish.yml

@@ -20,6 +20,9 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: "3.9"
+      - name: Install gettext for translations
+        run: |
+          sudo apt-get install gettext
       - name: Build package
         run: |
           python -m pip install -U pip build

.github/workflows/tests.yml

@@ -1,5 +1,13 @@
 name: continuous-integration
 
+# README
+# ======
+#
+# All the jobs are defined with `matrix` for OS and Python version, even if we
+# only run them on one combination of OS/Python. The reason for this is you get
+# a nice side-effect that the OS and Python version of the job are listed in
+# parentheses next to the job name in the Actions UI.
+
 # This prevents workflows from being run twice on PRs
 # ref: https://github.community/t/how-to-trigger-an-action-on-push-or-pull-request-but-not-both/16662
 on:
@@ -14,85 +22,123 @@ env:
 
 jobs:
   lint:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - name: Setup Python
+        uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - uses: pre-commit/action@v3.0.0
 
-  tests:
-    runs-on: ${{ matrix.os }}
+  # run our test suite on various combinations of OS / Python / Sphinx version
+  run-pytest:
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11-dev"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         include:
+          # legacy test
+          - os: ubuntu-latest
+            python-version: "3.7"
+            sphinx-version: "4.2"
+          # macos test
           - os: macos-latest
-            python-version: "3.9"
+            python-version: "3.11"
+          # windows test
           - os: windows-latest
-            python-version: "3.9"
-
+            python-version: "3.11"
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
-
       - 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 .[coverage]
-          python -m pip list
-
-      - name: Test Sphinx==4.2
-        if: matrix.python-version == '3.7'
+          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 sphinx==4.2
-          python -m pip list
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install -e .[test] sphinx==${{ matrix.sphinx-version }}
+      - 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 --color=yes --cov pydata_sphinx_theme --cov-branch --cov-report term-missing:skip-covered --cov-fail-under ${{ env.COVERAGE_THRESHOLD }}
 
-      - name: Build docs to store
+  # Build our site on the 3 major OSes and check for Sphinx warnings
+  build-site:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - 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]
+      - name: Show installed versions
+        run: python -m pip list
+      - name: Build docs
         run: sphinx-build -b html docs/ docs/_build/html --keep-going -w warnings.txt
-
-      - name: Check that there are no unexpected Sphinx warnings
-        if: matrix.python-version == '3.9'
+      - name: Check for unexpected Sphinx warnings
         run: python tests/check_warnings.py
 
-      - name: Run the tests
-        run: pytest --color=yes --cov pydata_sphinx_theme --cov-branch --cov-report term-missing:skip-covered --cov-fail-under ${{ env.COVERAGE_THRESHOLD }}
-
-      - name: Upload coverage
-        if: ${{ always() }}
-        run: codecov
-
   # Run local Lighthouse audit against built site
   audit:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8"]
-
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
+      - 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 .[coverage]
-
+          python -m pip install -e .[doc]
+      - name: Show installed versions
+        run: python -m pip list
       # We want to run the audit on a simplified documentation build so that
       # the audit results aren't affected by non-theme things like extensions.
       # Here we copy over just the kitchen sink into an empty docs site with
@@ -106,7 +152,6 @@ jobs:
           echo 'html_theme = "pydata_sphinx_theme"' > audit/site/conf.py
           echo '.. toctree::\n   :glob:\n\n   *' >> audit/site/index.rst
           sphinx-build audit/site audit/_build
-
       # The lighthouse audit runs directly on the HTML files, no serving needed
       - name: Audit with Lighthouse
         uses: treosh/lighthouse-ci-action@v9
@@ -118,30 +163,28 @@ jobs:
 
   # Generate a profile of the code and upload as an artifact
   profile:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8"]
-
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
+      - 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]
+      - name: Show installed versions
+        run: python -m pip list
       - name: Generate a profile
-        run: |
-          nox -s profile
+        run: nox -s profile
         continue-on-error: true
-
       - uses: actions/upload-artifact@v3
         with:
           name: profile-results

.gitignore

@@ -46,10 +46,6 @@ coverage.xml
 *.cover
 .hypothesis/
 
-# Translations
-*.mo
-*.pot
-
 # Django stuff:
 *.log
 local_settings.py
@@ -113,11 +109,15 @@ node_modules/
 .vscode
 .idea
 
+# MacOSX store files
+**/.DS_Store
+
+# THEME FILES
 # files from the gallery screenshots
 docs/_static/gallery
 
 # Our site profile tests
 profile.svg
 
-# MacOSX store files
-**/.DS_Store
+# Compiled translation files (are compiled at build time)
+src/pydata_sphinx_theme/locale/*/*/*.mo

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ default_language_version:
 
 repos:
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.0-alpha.4
+    rev: v2.7.1
     hooks:
       - id: prettier
         # Exclude the HTML, since it doesn't understand Jinja2
@@ -43,3 +43,8 @@ repos:
     hooks:
       - id: djlint-jinja
         types_or: ["html"]
+
+  - repo: https://github.com/PyCQA/doc8
+    rev: v1.1.1
+    hooks:
+      - id: doc8

README.md

@@ -1,16 +1,17 @@
 # The PyData Sphinx Theme
 
-[![pypi](https://img.shields.io/pypi/v/pydata-sphinx-theme)](https://pypi.org/project/pydata-sphinx-theme/)
-[![conda-forge](https://img.shields.io/conda/vn/conda-forge/pydata-sphinx-theme.svg)](https://anaconda.org/conda-forge/pydata-sphinx-theme)
-[![continuous-integration](https://github.com/pydata/pydata-sphinx-theme/actions/workflows/tests.yml/badge.svg)](https://github.com/pydata/pydata-sphinx-theme/actions/workflows/tests.yml)
-[![docs](https://readthedocs.org/projects/pydata-sphinx-theme/badge/)](https://readthedocs.org/projects/pydata-sphinx-theme/builds/)
-[![codecov](https://codecov.io/gh/pydata/pydata-sphinx-theme/branch/main/graph/badge.svg?token=NwOObjYacn)](https://codecov.io/gh/pydata/pydata-sphinx-theme)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-yellow.svg)](https://github.com/pydata/pydata-sphinx-theme/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/pydata-sphinx-theme?logo=python&logoColor=white&color=orange)](https://pypi.org/project/pydata-sphinx-theme/)
+[![conda-forge](https://img.shields.io/conda/vn/conda-forge/pydata-sphinx-theme.svg?logo=anaconda&logoColor=white&color=orange)](https://anaconda.org/conda-forge/pydata-sphinx-theme)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/pydata/pydata-sphinx-theme/tests.yml?logo=github&logoColor=white)](https://github.com/pydata/pydata-sphinx-theme/actions/workflows/tests.yml)
+[![Read the Docs (version)](https://img.shields.io/readthedocs/pydata-sphinx-theme/latest?logo=readthedocs&logoColor=white)](https://readthedocs.org/projects/pydata-sphinx-theme/builds/)
+[![Codecov](https://img.shields.io/codecov/c/github/pydata/pydata-sphinx-theme?logo=codecov&logoColor=white)](https://codecov.io/gh/pydata/pydata-sphinx-theme)
 
 A clean, three-column, Bootstrap-based Sphinx theme by and for the [PyData community](https://pydata.org).
 
-- 📚 Documentation: https://pydata-sphinx-theme.readthedocs.io/en/stable
-- 💡 Examples: https://pydata-sphinx-theme.readthedocs.io/en/stable/examples
-- 🙌 Contribute: https://pydata-sphinx-theme.readthedocs.io/en/stable/community
+- :books: Documentation: https://pydata-sphinx-theme.readthedocs.io/en/stable
+- :bulb: Examples: https://pydata-sphinx-theme.readthedocs.io/en/stable/examples
+- :raised_hands: Contribute: https://pydata-sphinx-theme.readthedocs.io/en/stable/community
 
 [![Example documentation with this theme](./docs/_static/theme_landing.png)](https://pydata-sphinx-theme.readthedocs.io/en/stable)
 

babel.cfg

@@ -0,0 +1,5 @@
+# See https://github.com/sphinx-doc/sphinx/blob/6.1.x/babel.cfg
+[jinja2: **.html]
+encoding = utf-8
+ignore_tags = script,style
+include_attrs = alt title summary placeholder

docs/_static/contributors.yaml

@@ -1,24 +1,24 @@
 - header: "@bollwyvl"
   image: https://avatars.githubusercontent.com/u/45380
-  link: https://github.com/bollwyvl
+  website: https://github.com/bollwyvl
 - header: "@jarrodmillman"
   image: https://avatars.githubusercontent.com/u/123428
-  link: https://github.com/jarrodmillman
+  website: https://github.com/jarrodmillman
 - header: "@hoetmaaiers"
   image: https://avatars.githubusercontent.com/u/468045
-  link: https://github.com/hoetmaaiers
+  website: https://github.com/hoetmaaiers
 - header: "@jorisvandenbossche"
   image: https://avatars.githubusercontent.com/u/1020496
-  link: https://github.com/jorisvandenbossche
+  website: https://github.com/jorisvandenbossche
 - header: "@damianavila"
   image: https://avatars.githubusercontent.com/u/1640669
-  link: https://github.com/damianavila
+  website: https://github.com/damianavila
 - header: "@drammock"
   image: https://avatars.githubusercontent.com/u/1810515
-  link: https://github.com/drammock
+  website: https://github.com/drammock
 - header: "@choldgraf"
   image: https://avatars.githubusercontent.com/u/1839645
-  link: https://github.com/choldgraf
+  website: https://github.com/choldgraf
 - header: "@12rambau"
   image: https://avatars.githubusercontent.com/u/12596392
-  link: https://github.com/12rambau
+  website: https://github.com/12rambau

docs/_static/custom.css

@@ -17,3 +17,41 @@
   background-color: var(--pst-color-success);
   opacity: 0.1;
 }
+
+/* custom CSS classes (used in docs/user_guide/extending.rst) NOTE: the begin
+ *  and end markers are necessary for partial file includes! don't remove them.
+ */
+
+/* begin-custom-color/* <your static path>/custom.css */
+
+div.admonition.admonition-olive {
+  border-color: olive;
+}
+div.admonition.admonition-olive > .admonition-title:before {
+  background-color: olive;
+}
+div.admonition.admonition-olive > .admonition-title:after {
+  color: olive;
+}
+/* end-custom-color */
+
+/* begin-custom-icon/* <your static path>/custom.css */
+
+div.admonition.admonition-icon > .admonition-title:after {
+  content: "\f24e"; /* the fa-scale icon */
+}
+/* end-custom-icon */
+
+/* begin-custom-youtube/* <your static path>/custom.css */
+
+div.admonition.admonition-youtube {
+  border-color: #ff0000; /* YouTube red */
+}
+div.admonition.admonition-youtube > .admonition-title:before {
+  background-color: #ff0000;
+}
+div.admonition.admonition-youtube > .admonition-title:after {
+  color: #ff0000;
+  content: "\f26c"; /* fa-solid fa-tv */
+}
+/* end-custom-youtube */