Merge remote-tracking branch 'origin/main' into trallard/update-ci

pydata · Apr 25, 2024 · 19b8572 · 19b8572
2 parents 0b74130 + cd064bd
commit 19b8572
Show file tree

Hide file tree

Showing 61 changed files with 1,409 additions and 3,172 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -5,7 +5,8 @@
   "features": {
     "ghcr.io/devcontainers-contrib/features/nox:2": {},
     "ghcr.io/devcontainers-contrib/features/pre-commit:2": {},
-    "ghcr.io/rocker-org/devcontainer-features/pandoc:1": {}
+    "ghcr.io/rocker-org/devcontainer-features/pandoc:1": {},
+    "ghcr.io/devcontainers/features/node:1": {}
   },
   "postCreateCommand": "pre-commit install"
 }
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -45,14 +45,16 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
-        sphinx-version: [""]
+        sphinx-version: ["rls"]
         include:
           # macos test
           - os: macos-latest
             python-version: "3.12"
+            sphinx-version: "rls"
           # windows test
           - os: windows-latest
             python-version: "3.12"
+            sphinx-version: "rls"
           # old Sphinx test
           - os: ubuntu-latest
             python-version: "3.9"
@@ -97,6 +99,7 @@ jobs:
         uses: codecov/codecov-action@v4
         with:
           fail_ci_if_error: true
+          verbose: true
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 

diff --git a/babel.cfg b/babel.cfg
@@ -1,4 +1,5 @@
-# See https://github.com/sphinx-doc/sphinx/blob/6.1.x/babel.cfg
+# See https://github.com/python-babel/babel/blob/2a1709a7768f6f07c3d2dbfdb03d3c8a6bd80aef/docs/messages.rst#extraction-method-mapping-and-configuration
+[python: **.py]
 [jinja2: **.html]
 encoding = utf-8
 ignore_tags = script,style

diff --git a/docs/_static/pydata-icon.js b/docs/_static/pydata-icon.js
@@ -0,0 +1,16 @@
+/*******************************************************************************
+ * Set a custom icon for PyData
+ */
+FontAwesome.library.add(
+  (faListOldStyle = {
+    prefix: "fa-custom",
+    iconName: "pydata",
+    icon: [
+      24, // viewBox width
+      24, // viewBox height
+      [], // ligature
+      "e002", // unicode codepoint - private use area
+      "M12.1,17.8v5.8l-5-2.9v-5.8L12.1,17.8z M12.1,12v5.8l-5-2.9V9.1L12.1,12z M17,9.1L12.1,12v5.8l4.9-2.9V9.1z M12.1,6.2L7,9.1l5,2.9L17,9.1L12.1,6.2z M17,9.1V3.3l-4.9-2.8v5.8L17,9.1z",
+    ],
+  })
+);
diff --git a/docs/_static/pydata-logo.png b/docs/_static/pydata-logo.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -13,6 +13,7 @@
 
 import pydata_sphinx_theme
 from sphinx.application import Sphinx
+from sphinx.locale import _
 
 sys.path.append(str(Path(".").resolve()))
 
@@ -89,6 +90,11 @@
     "jupyter": ("Jupyter", "https://jupyter.org"),
 }
 
+# -- sphinx_togglebutton options ---------------------------------------------
+togglebutton_hint = str(_("Click to expand"))
+togglebutton_hint_hide = str(_("Click to collapse"))
+
+
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "pydata_sphinx_theme"
@@ -153,9 +159,7 @@
         {
             "name": "PyData",
             "url": "https://pydata.org",
-            "icon": "_static/pydata-logo.png",
-            "type": "local",
-            "attributes": {"target": "_blank"},
+            "icon": "fa-custom fa-pydata",
         },
     ],
     # alternative way to set twitter and github header icons
@@ -228,7 +232,7 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
-html_js_files = ["custom-icon.js"]
+html_js_files = ["pydata-icon.js", "custom-icon.js"]
 todo_include_todos = True
 
 # -- favicon options ---------------------------------------------------------

diff --git a/docs/examples/gallery.md b/docs/examples/gallery.md
@@ -38,8 +38,8 @@ Thanks for your support!
 - title: Feature-engine
   link-alt: Feature-engine docs
   link: https://feature-engine.readthedocs.io/
-- title: idtracker.ai
-  link-alt: idtracker.ai docs
+- title: idtracker&period;ai
+  link-alt: idtracker&period;ai docs
   link: https://idtracker.ai/
 - title: MegEngine
   link-alt: MegEngine docs

diff --git a/docs/index.md b/docs/index.md
@@ -21,13 +21,11 @@ A clean, Bootstrap-based Sphinx theme by and for [the PyData community](https://
 - header: "{fas}`circle-half-stroke;pst-color-primary` Light / Dark theme"
   content: "Users can toggle between light and dark themes interactively."
 - header: "{fas}`palette;pst-color-primary` Customizable UI and themes"
-  content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design](user_guide/web-components)."
+  content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design components](user_guide/web-components)."
 - header: "{fab}`python;pst-color-primary` Supports PyData and Jupyter"
-  content: "CSS and UI support for Jupyter extensions and PyData execution outputs."
-  link: "examples/pydata.html"
+  content: "CSS and UI support for [Jupyter extensions](examples/execution) and [PyData execution outputs](examples/pydata.ipynb)."
 - header: "{fas}`lightbulb;pst-color-primary` Example Gallery"
-  content: "See our gallery of projects that use this theme."
-  link: "examples/gallery.html"
+  content: "See [our gallery](examples/gallery.md) of projects that use this theme."
 ```
 
 ```{seealso}

diff --git a/docs/user_guide/accessibility.md b/docs/user_guide/accessibility.md
@@ -33,6 +33,14 @@ page that lacks metadata, please open a pull request to add it!
 - We have improved how we assign text colors to interactive elements such as buttons and dropdowns to ensure that they meet
   WCAG 2 AA or AAA contrast requirements.
 
+### Keyboard Navigation Support
+
+For all buttons, dropdowns, tabbed panels, hamburger menus, modals, overlays,
+links and other interactive elements, we have worked to ensure they:
+
+- Have a visible focus indicator (WCAG 2.4.7)
+- Can be accessed via keyboard navigation (WCAG 2.1.1)
+
 ## What You Can Do
 
 ### Site configuration

diff --git a/docs/user_guide/light-dark.rst b/docs/user_guide/light-dark.rst
@@ -59,14 +59,14 @@ For example to define a different background color for both the light and dark t
     html[data-theme="light"] {
 
         /* whatever you want to change */
-        background: white;
+        background-color: white;
     }
 
     /* anything related to the dark theme */
     html[data-theme="dark"] {
 
         /* whatever you want to change */
-        background: black;
+        background-color: black;
     }
 
 A complete list of the colors used in this theme can be found in the :doc:`CSS style section <styling>`.

diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
@@ -117,18 +117,18 @@ Here is an overview of the colors available in the theme (change theme mode to s
     </style>
 
     <p>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-primary sd-bg-text-primary">primary</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-secondary sd-bg-text-secondary">secondary</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-accent sd-bg-text-secondary">accent</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-success sd-bg-text-success">success</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-info sd-bg-text-info">info</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-warning sd-bg-text-warning">warning</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-danger sd-bg-text-danger">danger</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-background">background</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-on-background">on-background</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-surface">surface</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-on-surface sd-bg-text-primary">on-surface</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-target">target</span>
+      <span class="sd-badge pst-badge pst-primary sd-bg-text-primary">primary</span>
+      <span class="sd-badge pst-badge pst-secondary sd-bg-text-secondary">secondary</span>
+      <span class="sd-badge pst-badge pst-accent sd-bg-text-secondary">accent</span>
+      <span class="sd-badge pst-badge pst-success sd-bg-text-success">success</span>
+      <span class="sd-badge pst-badge pst-info sd-bg-text-info">info</span>
+      <span class="sd-badge pst-badge pst-warning sd-bg-text-warning">warning</span>
+      <span class="sd-badge pst-badge pst-danger sd-bg-text-danger">danger</span>
+      <span class="sd-badge pst-badge pst-background">background</span>
+      <span class="sd-badge pst-badge pst-on-background">on-background</span>
+      <span class="sd-badge pst-badge pst-surface">surface</span>
+      <span class="sd-badge pst-badge pst-on-surface sd-bg-text-primary">on-surface</span>
+      <span class="sd-badge pst-badge pst-target">target</span>
     </p>
 
 

diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
@@ -4,16 +4,31 @@
 Sphinx Design Components
 ========================
 
-The PyData Sphinx Theme uses `sphinx-design <https://sphinx-design.readthedocs.io/en/latest/index.html>`__
-to add several UI components and provide extra flexibility for content creation.
-These include badges, buttons, cards, and tabs, among other components.
-This theme provides custom CSS to ensure that `sphinx-design <https://sphinx-design.readthedocs.io/en/latest/index.html>`__ elements look and feel consistent with this theme.
+On this page, you will find user interface components such as badges, buttons,
+cards, and tabs.
+
+The components on this page are **not provided by PyData Theme**. They are
+provided by `Sphinx Design <https://sphinx-design.readthedocs.io/en/pydata-theme/index.html>_` (a Sphinx extension). This means that if you wish
+to use the components on this page, you must install Sphinx Design separately and add it to your `conf.py`.
 
 .. seealso::
 
-    For more information about how to use these extensions, see `the sphinx-design documentation <https://sphinx-design.readthedocs.io/en/latest/index.html>`_.
+    To add the Sphinx Design extension to your Sphinx project, refer to `Sphinx
+    Design - Getting Started
+    <https://sphinx-design.readthedocs.io/en/pydata-theme/get_started.html>`_.
+
+Contributors to both projects have worked to ensure compatible styling so that
+Sphinx Design components look and feel consistent with the PyData Theme.
+
+This page shows you how the Sphinx Design components would look on your site if
+you were to use them in combination with the PyData Theme. Sphinx Design also
+provides a `PyData-themed version of the Sphinx Design site
+<https://sphinx-design.readthedocs.io/en/pydata-theme/>`__; however, their site
+use an older version of this theme.
 
-Below you can find some examples of the components created with the :code:`sphinx-design` extension.
+Any customizations you make to the theme could affect how these components
+appear on your site. So what you see on this page might not match exactly what
+you see on your site even if your site uses this theme.
 
 .. _badges-buttons: