diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
index ce14278543..277f37b240 100644
--- a/.git-blame-ignore-revs
+++ b/.git-blame-ignore-revs
@@ -5,9 +5,11 @@
# https://git-scm.com/docs/git-config#Documentation/git-config.txt-blameignoreRevsFile
# https://github.com/pydata/pydata-sphinx-theme/pull/713
#
-90550b66ace16a370caa446e54698b126fda740b # initial black-format
-236d4c6d1f10f5da064d929e9eb594daecf23551 # apply black 20.8b1 format
-69f1a42a3b184f4ba4c98f1745779a277d56c5e2 # [pre-commit.ci] Automatic linting and formatting fixes
-a35529c9ee8d5863613df40787cda0021b3e0128 # Manual fixes for stylelint
-ce583b8f3136d52e8056c9a651bf6f92e7922f79 # Manual adjustments to autofixes
-d1ee9eb7a132cde51433e9594513319fdab41f2f # Autofix (stylelint)
+90550b66ace16a370caa446e54698b126fda740b # initial black-format
+236d4c6d1f10f5da064d929e9eb594daecf23551 # apply black 20.8b1 format
+69f1a42a3b184f4ba4c98f1745779a277d56c5e2 # [pre-commit.ci] Automatic linting and formatting fixes
+a35529c9ee8d5863613df40787cda0021b3e0128 # Manual fixes for stylelint
+ce583b8f3136d52e8056c9a651bf6f92e7922f79 # Manual adjustments to autofixes
+d1ee9eb7a132cde51433e9594513319fdab41f2f # Autofix (stylelint)
+0f3aa5ca174fe1534ef4817d42f0e2ffa7d9d921 # [pre-commit.ci] Automatic linting and formatting fixes
+9c5a3d592d03849bd050fe946b246145ad171605 # Automated and manual fixes for pre-commits
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index ad1c49c2c4..04b6bdc64c 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -9,11 +9,11 @@ ci:
# Fix the node version to avoid a GLIBC error
# ref: https://stackoverflow.com/questions/71939099/bitbucket-pipeline-error-installing-pre-commit-ts-lint/71940852#71940852
default_language_version:
- node: 16.14.2
+ node: 22.9.0
repos:
- - repo: https://github.com/pre-commit/mirrors-prettier
- rev: v4.0.0-alpha.8
+ - repo: "https://github.com/pycontribs/mirrors-prettier"
+ rev: v3.3.3
hooks:
- id: prettier
# Exclude the HTML, since it doesn't understand Jinja2
@@ -21,29 +21,26 @@ repos:
# exclude the pytest-regressions folder tests/test_ally
exclude: .+\.html|webpack\.config\.js|tests/test_a11y/
- - repo: https://github.com/psf/black
- rev: 24.10.0
- hooks:
- - id: black
-
- - repo: https://github.com/astral-sh/ruff-pre-commit
+ - repo: "https://github.com/astral-sh/ruff-pre-commit"
rev: "v0.7.2"
hooks:
- id: ruff
+ args: [--exit-non-zero-on-fix]
+ - id: ruff-format
- - repo: https://github.com/asottile/pyupgrade
+ - repo: "https://github.com/asottile/pyupgrade"
rev: v3.19.0
hooks:
- id: pyupgrade
args: [--py37-plus]
- - repo: https://github.com/Riverside-Healthcare/djLint
+ - repo: "https://github.com/Riverside-Healthcare/djLint"
rev: v1.35.4
hooks:
- id: djlint-jinja
types_or: ["html"]
- - repo: https://github.com/PyCQA/doc8
+ - repo: "https://github.com/PyCQA/doc8"
rev: v1.1.2
hooks:
- id: doc8
@@ -53,12 +50,12 @@ repos:
hooks:
- id: nbstripout
- - repo: https://github.com/mondeja/pre-commit-po-hooks
+ - repo: "https://github.com/mondeja/pre-commit-po-hooks"
rev: v1.7.3
hooks:
- id: remove-metadata
- - repo: https://github.com/thibaudcolas/pre-commit-stylelint
+ - repo: "https://github.com/thibaudcolas/pre-commit-stylelint"
rev: v16.10.0
hooks:
- id: stylelint
@@ -68,3 +65,9 @@ repos:
# stylelint itself needs to be here when using additional_dependencies.
- stylelint@16.5.0
- stylelint-config-standard-scss@13.1.0
+
+ - repo: "https://github.com/pre-commit/pre-commit-hooks"
+ rev: v5.0.0
+ hooks:
+ - id: trailing-whitespace
+ - id: end-of-file-fixer
diff --git a/docs/_extension/component_directive.py b/docs/_extension/component_directive.py
index 07ffcf66f0..334c798695 100644
--- a/docs/_extension/component_directive.py
+++ b/docs/_extension/component_directive.py
@@ -6,6 +6,7 @@
"""
import re
+
from pathlib import Path
from typing import Any, Dict, List
@@ -14,6 +15,7 @@
from sphinx.util import logging
from sphinx.util.docutils import SphinxDirective
+
logger = logging.getLogger(__name__)
diff --git a/docs/_extension/gallery_directive.py b/docs/_extension/gallery_directive.py
index 80642c5455..b34a701ce2 100644
--- a/docs/_extension/gallery_directive.py
+++ b/docs/_extension/gallery_directive.py
@@ -19,6 +19,7 @@
from sphinx.util.docutils import SphinxDirective
from yaml import safe_load
+
logger = logging.getLogger(__name__)
@@ -76,7 +77,7 @@ def run(self) -> List[nodes.Node]:
path_doc = Path(path_doc).parent
path_data = (path_doc / path_data_rel).resolve()
if not path_data.exists():
- logger.info(f"Could not find grid data at {path_data}.")
+ logger.info("Could not find grid data at %s.", path_data)
nodes.text("No grid data found at {path_data}.")
return
yaml_string = path_data.read_text()
diff --git a/docs/community/design-system.md b/docs/community/design-system.md
new file mode 100644
index 0000000000..e09ec372e5
--- /dev/null
+++ b/docs/community/design-system.md
@@ -0,0 +1,190 @@
+# PyData Sphinx Theme Design System
+
+The Pydata Sphinx Theme is committed to maintaining a theme that supports industry standards;
+the design system must be included.
+Whether choosing how to configure your theme or making changes to the design system itself,
+consider the most recent version of the Web Content Accessibility Guidelines
+(WCAG) to make sure the community continues to support documentation access for everyone.
+
+## Guiding Principles
+
+### Accessibility
+
+Accessibility is at the core of the PyData Sphinx theme.
+All design decisions are made with [WCAG 2.1](https://www.w3.org/TR/WCAG21/) conformance in mind,
+ensuring that the theme is usable by people of all abilities.
+Accessibility is a priority to make the theme inclusive for all users.
+
+### Open Source Collaboration
+
+As an open-source project, collaboration and transparency are key principles:
+
+1. **Clear Guidelines:** All components, color palettes, and typography rules must be documented.
+2. **Open Feedback:** Designers, developers, users and maintainers are encouraged
+ to give feedback on the theme, helping to improve its functionality and usability over time.
+ If you’d like to provide feedback, please open an issue on the
+ [PyData Sphinx Theme GitHub repository.](https://github.com/pydata/pydata-sphinx-theme)
+3. **Community Driven:** The theme grows and evolves based on the needs and
+ suggestions of the open-source community.
+
+## Typography
+
+### Typeface
+
+PyData Sphinx uses default system fonts.
+
+### Type Scale
+
+A type scale refers to the multiple by which font sizes increase.
+You can find more about typographic scales at [Typographic Scale](https://designcode.io/typographic-scales).
+For content-heavy websites, a medium contrast scale, which provides balanced
+contrast between heading sizes without overly large jumps, is ideal,
+typically ranging from `1.2x` to `1.33x`.
+
+The PST type scale was updated (August 2024) to improve the accessibility of the
+overall type system and increase visual contrast between the headings.
+The PST type scale uses the Minor Third scale (`1.2x`) with values rounded to the
+nearest even whole number.
+Except for the H4 to H3 transition, all headings have a minimum of a `1.2x` increase,
+which is an improvement over the previous scale.
+
+### Styles
+
+#### Headings
+
+Headings create structure and hierarchy within the content.
+They range from `H1` to `H6`, with each level decreasing in size and importance.
+
+| Style | Size (`px`) | Size (`rem`) | Weight | Use / Notes |
+| :-------- | :---------- | :----------- | :----- | :------------------------------- |
+| Heading 1 | 42 | 2.625 | 600 | Main page titles (use only once) |
+| Heading 2 | 34 | 2.125 | 600 | Section titles |
+| Heading 3 | 28 | 1.750 | 600 | Subsections within H2 |
+| Heading 4 | 24 | 1.500 | 600 | Tertiary level headings |
+| Heading 5 | 20 | 1.250 | 600 | Less prominent headings |
+| Heading 6 | 16 | 1.000 | 600 | Lowest level headings |
+
+Always use headings in logical order (`H1`, `H2`, `H3`, etc.) without skipping levels,
+to help assistive tech such as screen readers interpret the structure of the page.
+Each page should have a single, unique `H1` to effectively define the page's purpose,
+improving search engine optimization (SEO) and accessibility for users who rely
+on assistive tech such as screen readers.
+
+#### Body
+
+Body text serves as the standard style for detailed content.
+It is primarily used for longer, detailed content such as paragraphs, articles,
+and descriptions, but may also apply to other areas such as modals, admonitions
+or sections where longer content needs to be displayed clearly.
+
+| Style | Size (`px`) | Size (`rem`) | Weight | Use / Notes |
+| :---- | :---------- | :----------- | :----- | :--------------------------------- |
+| Body | 16 | 1.000 | 400 | Standard text size for readability |
+
+While there is no absolute minimum text size, for optimum readability,
+body text should be at least `16px`.
+
+#### Links
+
+Links must be styled in a way that makes them visually distinct from regular text.
+All links should be underlined in addition to being color-coded,
+as [color alone should not be used to convey meaning](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html).
+
+| Style | Size (`px`) | Size (`rem`) | Weight | Use / Notes |
+| :---- | :---------- | :----------- | :----- | :-------------------------------- |
+| Links | 16 | 1.000 | 400 | Always underlined and color-coded |
+
+Links also have a hover and focus interactive state.
+Hover and focus states should always show a change in color and visual design
+to provide clear feedback for interactive elements.
+
+Links are used to navigate between different pages or sections and to redirect
+readers to external sources.
+They are visually distinct from buttons, which are used to perform actions within
+the current page or context and should not trigger actions like submitting forms
+or toggling components.
+
+#### Code Text
+
+Code text is used to display inline code snippets or larger blocks of code.
+It uses a monospaced font. The theme also includes interactive states for code
+text including links.
+
+### Type Color
+
+Text color plays a crucial role in ensuring that content is legible and accessible.
+In the PyData Sphinx theme, we use a predefined set of colors to ensure readability,
+visual hierarchy, and consistency across different elements.
+Each text color is designed to meet accessibility guidelines, ensuring sufficient
+contrast between text and background.
+
+When using colors in text, ensure that it meets the minimum
+[WCAG color contrast accessibility criterion](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#contrast-minimum).
+Color alone should not be used to indicate meaning.
+For example, text that is a link should not be indicated solely by color
+but also with an underline.
+This helps ensure that users who have difficulty distinguishing colors can still identify links.
+Semantic colors (such as for success, warning, or error messages) can be used to
+convey meaning, but color should not be the only indicator.
+Pair these colors with icons or text labels to ensure clarity.
+
+### Relevant Links
+
+For further reference, you can access the following resources related to the
+typography in the PyData Sphinx theme:
+
+1. **GitHub Repository:** The source code for the PyData Sphinx theme is available on GitHub.
+ You can find the specific file that defines the typography settings,
+ including font stacks, sizes, and weights in the
+ [`fonts.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_fonts.scss).
+2. **Figma Design File:** The Figma file contains the visual design and specifications
+ for the typography styles, including font sizes, line heights,
+ and spacing used throughout the theme.
+ You can access it [through this link to the Figma file](https://www.figma.com/design/BHkBFxg1Qg0h5RApUw1ZrR/PyData-Design-System---Ongoing?node-id=2-7).
+
+### References
+
+1. [https://carbondesignsystem.com/elements/typography/overview/](https://carbondesignsystem.com/elements/typography/overview/)
+2. [https://canvas.workday.com/styles/tokens/type](https://canvas.workday.com/styles/tokens/type)
+3. [https://atlassian.design/foundations/typography-beta](https://atlassian.design/foundations/typography-beta)
+
+---
+
+## Color
+
+The PyData Sphinx theme uses a well-defined color palette to ensure consistency,
+readability, and accessibility across the entire design system.
+This color palette is available for both light and dark themes.
+This document explains how to use the theme's color system
+
+### Base Colors
+
+Base colors form the foundation of the theme and are used across primary UI elements
+like buttons, backgrounds, and text. They maintain consistency throughout the interface.
+
+- **Primary**: The main color for major actions and interactive elements.
+- **Secondary**: A supporting color for secondary actions and highlights.
+- **Accent**: An emphasis color used sparingly for highlighting content.
+- **Gray (Neutral)**: Used for typography, borders, and backgrounds.
+- **Foundation Colors**: Black and white base colors used for backgrounds and
+ surfaces (for example, cards, containers, modals) in light and dark modes.
+
+Color variables are also documented in the [](../user_guide/styling.rst) section
+of the User Guide.
+
+### Semantic Colors
+
+Semantic colors, colors named for what they represent and how they are used,
+are provided for success, errors, warnings, and information.
+Using these colors as named ensures users can easily understand system feedback
+through visual cues.
+
+### Relevant Links
+
+For further reference, you can access the following resources related to colors
+in the PyData Sphinx theme:
+
+1. **GitHub Repository:** You find all the PyData Sphinx theme colors in the
+ [`color.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_color.scss)
+2. **Figma Design File:** For specific color codes and detailed use cases,
+ refer to the [Figma Design File](https://www.figma.com/design/BHkBFxg1Qg0h5RApUw1ZrR/PyData-Design-System---Ongoing?node-id=2-160).
diff --git a/docs/community/index.md b/docs/community/index.md
index 220c4e6c56..27978d8927 100644
--- a/docs/community/index.md
+++ b/docs/community/index.md
@@ -29,4 +29,5 @@ practices/*
contributors
inspiration
+design-system
```
diff --git a/docs/community/topics/accessibility.md b/docs/community/topics/accessibility.md
index 957b4fcb5e..c22e4724be 100644
--- a/docs/community/topics/accessibility.md
+++ b/docs/community/topics/accessibility.md
@@ -1,20 +1,63 @@
-# Accessibility checks
+# Accessibility checks and manual auditing
-```{note}
-April-2023: we are currently
-[re-evaluating how we do accessibility checks](https://github.com/pydata/pydata-sphinx-theme/issues/1168)
-and reporting, so this may change soon.
+As part of our commitment to making this theme accessible, we run automated
+checks against all the pages under [](../../examples/kitchen-sink/index.rst).
+
+The accessibility check is run every time that a pull request is created on
+GitHub. We forbid merging a pull request into the codebase if it breaks this
+check.
+
+## Running the checks locally
+
+If you are [developing the theme locally](../setup.md), the simplest way to run
+the accessibility checks on your computer is:
+
+```sh
+tox run -m a11y
```
-In general, accessibility-checking tools can find a limited number of common HTML patterns that assistive technology
-can't help users understand.
+## Technical details
+
+The main two technologies we use to write and run accessibility checks are
+[Playwright for Python](https://playwright.dev/python/) and
+[axe-core](https://github.com/dequelabs/axe-core).
+
+Playwright is the successor to a similar library called Puppeteer. It provides a
+way to programmatically script a web browser to open, operate, inspect, and test
+web pages. Axe-core is a suite of accessibility checks written as a JavaScript
+program. The program is meant to be injected into a web page. Once injected, it
+examines the page for common accessibility failures, such as low contrast text.
+Our accessibility test suite uses Playwright to inject Axe-core into each of the
+Kitchen Sink pages plus a few other key pages in this documentation. We also
+wrote a few other Playwright scripts to ensure that certain theme components can
+be accessed using only the keyboard. All of our tests currently live in a file
+called
+[test_a11y.py](https://github.com/pydata/pydata-sphinx-theme/blob/main/tests/test_a11y.py).
+:::{note}
+We would love contributions that add more accessibility checks to our test
+suite.
+:::
+
+We have also made these tests part of our continuous integration process, so
+they are run in the cloud before we merge in new changes to the theme. We
+use the following tools:
+
+- GitHub Actions to provision machines in the cloud
+- `tox` to install the needed dependencies on those machines
+- `Pytest` with the Playwright plug-in to run the tests.
-## Accessibility checks as part of our development process
+Look for the string "accessibility" in the file
+[CI.yml](https://github.com/pydata/pydata-sphinx-theme/blob/main/.github/workflows/CI.yml)
+to find how we have configured GitHub Actions.
-We run a [Lighthouse](https://developers.google.com/web/tools/lighthouse) job in our CI/CD, which generates a "score" for all pages in our **Kitchen Sink** example documentation.
-The configuration for Lighthouse can be found in the `.github/workflows/lighthouserc.json` file.
+## Known limitations and manual auditing
-For more information about configuring Lighthouse, see [the Lighthouse documentation](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md).
-For more information about Accessibility in general, see [](../../user_guide/accessibility.md).
+We are well aware that automated checks fall far short of comprehensive
+accessibility auditing and testing, so we also conducted an accessibility audit
+of three pages from the theme docs. We collected those findings in an issue on
+GitHub, [May 2024 PyData Theme audit
+findings](https://github.com/Quansight-Labs/czi-scientific-python-mgmt/issues/72)
-We have also recently added automated tests using [Playwright](https://playwright.dev/python/) and [axe-core](https://github.com/dequelabs/axe-core) to improve our accessibility testing and reporting.
+Nearly all of the issues have been fixed, but of course things do break / have
+already broken, and some things may have never been discovered, so please
+[create a GitHub issue](https://github.com/pydata/pydata-sphinx-theme/issues/new) if you find something inaccessible.
diff --git a/docs/conf.py b/docs/conf.py
index de9295db7b..afab8132c3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -8,6 +8,7 @@
# -- Path setup --------------------------------------------------------------
import os
import sys
+
from pathlib import Path
from typing import Any, Dict
@@ -16,6 +17,7 @@
import pydata_sphinx_theme
+
sys.path.append(str(Path(".").resolve()))
# -- Project information -----------------------------------------------------
@@ -113,6 +115,7 @@
# Exclude copy button from appearing over notebook cell numbers by using :not()
# The default copybutton selector is `div.highlight pre`
# https://github.com/executablebooks/sphinx-copybutton/blob/master/sphinx_copybutton/__init__.py#L82
+copybutton_exclude = ".linenos, .gp"
copybutton_selector = ":not(.prompt) > div.highlight pre"
# -- Options for HTML output -------------------------------------------------
@@ -162,9 +165,9 @@
"header_links_before_dropdown": 4,
"icon_links": [
{
- "name": "Twitter",
- "url": "https://twitter.com/PyData",
- "icon": "fa-brands fa-twitter",
+ "name": "X",
+ "url": "https://x.com/PyData",
+ "icon": "fa-brands fa-x-twitter",
},
{
"name": "GitHub",
@@ -191,7 +194,8 @@
},
"use_edit_page_button": True,
"show_toc_level": 1,
- "navbar_align": "left", # [left, content, right] For testing that the navbar items align properly
+ # [left, content, right] For testing that the navbar items align properly
+ "navbar_align": "left",
# "show_nav_level": 2,
"announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
"show_version_warning_banner": True,
@@ -293,10 +297,15 @@
def setup_to_main(
app: Sphinx, pagename: str, templatename: str, context, doctree
) -> None:
- """Add a function that jinja can access for returning an "edit this page" link pointing to `main`."""
+ """
+ Add a function that jinja can access for returning an "edit this page" link
+ pointing to `main`.
+ """
def to_main(link: str) -> str:
- """Transform "edit on github" links and make sure they always point to the main branch.
+ """
+ Transform "edit on github" links and make sure they always point to the
+ main branch.
Args:
link: the link to the github edit interface
diff --git a/docs/examples/gallery.md b/docs/examples/gallery.md
index 049daedd25..91f170327c 100644
--- a/docs/examples/gallery.md
+++ b/docs/examples/gallery.md
@@ -44,6 +44,9 @@ Thanks for your support!
- title: idtracker.ai
link-alt: idtracker.ai docs
link: https://idtracker.ai/
+- title: itom measurement and simulation software
+ link-alt: itom documentation
+ link: https://itom-project.github.io/latest/docs/index.html
- title: MegEngine
link-alt: MegEngine docs
link: https://www.megengine.org.cn/doc/stable/en/index.html
diff --git a/docs/examples/pydata.ipynb b/docs/examples/pydata.ipynb
index 64c273503c..df86e223d3 100644
--- a/docs/examples/pydata.ipynb
+++ b/docs/examples/pydata.ipynb
@@ -29,6 +29,7 @@
"import numpy as np\n",
"import pandas as pd\n",
"\n",
+ "\n",
"rng = np.random.default_rng(seed=15485863)\n",
"data = rng.standard_normal((100, 26))\n",
"df = pd.DataFrame(data, columns=list(string.ascii_lowercase))\n",
@@ -51,8 +52,10 @@
"import ipywidgets as widgets\n",
"import numpy as np\n",
"import pandas as pd\n",
+ "\n",
"from IPython.display import display\n",
"\n",
+ "\n",
"tab = widgets.Tab()\n",
"\n",
"descr_str = \"Hello\"\n",
@@ -65,9 +68,9 @@
"\n",
"# render in output widgets\n",
"with widget_images:\n",
- " display(pd.DataFrame(np.random.randn(10,10)))\n",
+ " display(pd.DataFrame(np.random.randn(10, 10)))\n",
"with widget_annotations:\n",
- " display(pd.DataFrame(np.random.randn(10,10)))\n",
+ " display(pd.DataFrame(np.random.randn(10, 10)))\n",
"\n",
"tab.children = [widget_images, widget_annotations]\n",
"tab.titles = [\"Images\", \"Annotations\"]\n",
@@ -90,6 +93,7 @@
"source": [
"import matplotlib.pyplot as plt\n",
"\n",
+ "\n",
"fig, ax = plt.subplots()\n",
"ax.scatter(df[\"a\"], df[\"b\"], c=df[\"b\"], s=3)"
]
@@ -125,10 +129,13 @@
"import plotly.express as px\n",
"import plotly.io as pio\n",
"\n",
+ "\n",
"pio.renderers.default = \"notebook\"\n",
"\n",
"df = px.data.iris()\n",
- "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\", color=\"species\", size=\"sepal_length\")\n",
+ "fig = px.scatter(\n",
+ " df, x=\"sepal_width\", y=\"sepal_length\", color=\"species\", size=\"sepal_length\"\n",
+ ")\n",
"fig"
]
},
@@ -149,11 +156,10 @@
"source": [
"import xarray as xr\n",
"\n",
+ "\n",
"data = xr.DataArray(\n",
- " np.random.randn(2, 3),\n",
- " dims=(\"x\", \"y\"),\n",
- " coords={\"x\": [10, 20]}, attrs={\"foo\": \"bar\"}\n",
- " )\n",
+ " np.random.randn(2, 3), dims=(\"x\", \"y\"), coords={\"x\": [10, 20]}, attrs={\"foo\": \"bar\"}\n",
+ ")\n",
"data"
]
},
@@ -174,8 +180,9 @@
"source": [
"from ipyleaflet import Map, basemaps\n",
"\n",
+ "\n",
"# display a map centered on France\n",
- "m = Map(basemap=basemaps.Esri.WorldImagery, zoom=5, center=[46.21, 2.21])\n",
+ "m = Map(basemap=basemaps.Esri.WorldImagery, zoom=5, center=[46.21, 2.21])\n",
"m"
]
}
diff --git a/docs/scripts/generate_collaborators_gallery.py b/docs/scripts/generate_collaborators_gallery.py
index 110abfb0f7..8a03c22f52 100644
--- a/docs/scripts/generate_collaborators_gallery.py
+++ b/docs/scripts/generate_collaborators_gallery.py
@@ -1,12 +1,17 @@
-"""Uses the GitHub API to list a gallery of all people with direct access to the repository."""
+"""
+Uses the GitHub API to list a gallery of all people with direct access to the
+repository.
+"""
import json
import shlex
+
from pathlib import Path
from subprocess import run
from yaml import dump
+
COLLABORATORS_API = "https://api.github.com/repos/pydata/pydata-sphinx-theme/collaborators?affiliation=direct"
print("Grabbing latest collaborators with GitHub API via GitHub's CLI...")
diff --git a/docs/scripts/update_kitchen_sink.py b/docs/scripts/update_kitchen_sink.py
index 4612e6687b..5a8f35d913 100644
--- a/docs/scripts/update_kitchen_sink.py
+++ b/docs/scripts/update_kitchen_sink.py
@@ -3,10 +3,13 @@
from pathlib import Path
from urllib.request import urlopen
+
EXTRA_MESSAGE = """\
.. note::
- The Kitchen Sink was generated from the `Sphinx Themes website `_, a community-supported showcase of themes for `Sphinx `_.
+ The Kitchen Sink was generated from the
+ `Sphinx Themes website `_, a community-supported showcase
+ of themes for `Sphinx `_.
Check it out to see other great themes.
.. button-link:: https://sphinx-themes.org
diff --git a/docs/user_guide/accessibility.md b/docs/user_guide/accessibility.md
index 3fe7d70a7f..11f63b516b 100644
--- a/docs/user_guide/accessibility.md
+++ b/docs/user_guide/accessibility.md
@@ -1,12 +1,15 @@
# Accessibility
-Creating and publishing content that does not exclude disabled users is a complex and iterative task.
+Creating and publishing content that does not exclude disabled users is a
+complex and iterative task.
While there is no one-size-fits-all solution to maintaining accessible content,
-the PyData Sphinx Theme and this documentation site use some techniques to avoid common content shortcomings.
+the PyData Sphinx Theme and this documentation site use some techniques to avoid
+common content shortcomings.
:::{note}
-Issues and pull requests to identify or fix accessibility issues on this theme or site are heartily welcomed!
+Issues and pull requests to identify or fix accessibility issues on this theme
+or site are heartily welcomed!
:::
## What We've Done
@@ -26,12 +29,18 @@ page that lacks metadata, please open a pull request to add it!
to choose from at https://github.com/Quansight-Labs/accessible-pygments.
- We recently revisited the PyData Sphinx theme color palette to ensure that
the colors we use meet WCAG 2 AA or AAA contrast requirements.
-- We also re-defined our `primary` and `secondary` colors to be more accessible and distinct from semantic colors used
- to denote success, warning, info, and danger contexts or information.
-- We simplified the color palette and removed some colors that were problematic in meeting WCAG 2 AA or AAA contrast requirements
- and for certain types of colorblindness.
-- 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.
+- We also re-defined our `primary` and `secondary` colors to be more accessible
+ and distinct from semantic colors used to denote success, warning, info, and
+ danger contexts or information.
+- We simplified the color palette and removed some colors that were problematic
+ in meeting WCAG 2 AA or AAA contrast requirements and for certain types of
+ colorblindness.
+- 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.
+
+To learn more about the PyData Sphinx Theme colors, check the [](../community/design-system.md)
+section.
### Keyboard Navigation Support
@@ -41,6 +50,11 @@ 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)
+### Testing and auditing
+
+We have also added automated tests and conducted manual audits. See
+[](../community/topics/accessibility.md).
+
## What You Can Do
### Site configuration
@@ -55,10 +69,12 @@ specifying at least the baseline natural language will help assistive technology
identify if the content is in a language the reader understands.
:::{hint}
-In your `conf.py` file, [specifying the language your docs are written in](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language) will propagate to the top-level `HTML` tag.
+In your `conf.py` file,
+[specifying the language your docs are written in](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language)
+will propagate to the top-level `HTML` tag.
```python
- language = "en"
+language = "en"
```
:::
@@ -80,71 +96,67 @@ For a simple site (no extra languages or versions), ensure `sphinx-sitemap`
is installed in your documentation environment, and modify your `conf.py`:
```python
- extensions += ["sphinx_sitemap"]
+extensions += ["sphinx_sitemap"]
- html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/")
- sitemap_locales = [None]
- sitemap_url_scheme = "{link}"
+html_baseurl = os.environ.get("SPHINX_HTML_BASE_URL", "http://127.0.0.1:8000/")
+sitemap_locales = [None]
+sitemap_url_scheme = "{link}"
```
:::
### Logo best practices
-If you use both light and dark themes, it's best to provide a logo that works well in both or to provide an alternative for the dark theme.
-If you have a logo, you can add alt-text to it by adding the following to your
-`conf.py`:
+We recommend that you support dark mode by providing either a single version of
+your logo that works well in both light and dark modes, or two separate
+versions. We also recommend that you provide alt text for your logo if you do
+not provide visible text.
-```python
- "logo": {
- "text": "PyData Theme",
- "image_dark": "_static/logo-dark.svg",
- "alt_text": "PyData Theme home",
- },
-```
+These recommendations are covered in detail at the page [](./branding.rst)
-Note the use of "home" in the alt text to indicate that the logo is also a link to the home page.
+### Test and inspect your site
-### In the Browser
+Several browser tools exist for interactively debugging the accessibility
+of a single page at a time and can be useful during the content development
+cycle.
-Several in-browser tools exist for interactively debugging the accessibility
-of a single page at a time and can be useful during the content development cycle.
+Non-interactive tools also exist for use with CI (continuous integration).
-### Built-in tools
+#### Browser tools
-Most major browsers, including [Firefox](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector)
-and [Chrome](https://developers.google.com/web/tools/chrome-devtools/accessibility/reference),
-have accessibility tools built-in as part of their web developer tools.
-These tools can help to quickly identify accessibility issues and often include links to standards.
+Most major browsers, including Firefox and Chrome, have built-in accessibility
+tools as part of their web developer tools. These tools can help to quickly
+identify accessibility issues and often include links to standards:
-#### tota11y
+- [Firefox Accessibility Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector)
+- [Chrome DevTools Accessibility](https://developer.chrome.com/docs/devtools/accessibility/reference)
-[tota11y](https://khan.github.io/tota11y/#Installation) is an open source
-"bookmarklet" which modifies the currently-loaded page in place and highlights
-several accessibility issues.
+There are also a few browser extensions that some of the maintainers of this
+theme use when working to make websites more accessible. Some of these include:
-#### WAVE
+- [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/)
+- [Axe DevTools](https://www.deque.com/axe/browser-extensions/)
+- [WAVE](https://wave.webaim.org/extension/)
-[WAVE](https://wave.webaim.org/extension/) is a proprietary (but _gratis_)
-browser extension which can highlight multiple issues.
+We have also found [Polypane](https://polypane.app/) to be a great tool (but it
+is not free and requires a license).
-:::{warning}
-Note that automated testing and extensions such as the ones mentioned above will at best catch 30-40% of accessibility issues.
-They are not a replacement for manual testing and having a perfect score on any of these tools does not mean that
-the site can be used by disabled users but instead signals that it follows some accessibility best practices.
-:::
-
-### In Continuous Integration
+#### Continuous Integration tools
-Several automated tools are available for assessing _glaring_ accessibility
-issues across some pages at once, usually with many configurable options.
+Two accessibility testing tools designed for continuous integration are
+[Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/getting-started.md)
+and [Pa11y CI](https://github.com/pa11y/pa11y-ci).
-#### Lighthouse
+The [foo-software/lighthouse-check-action](https://github.com/foo-software/lighthouse-check-action)
+may be helpful if the code for your site is hosted on GitHub.
-[Lighthouse](https://developers.google.com/web/tools/lighthouse) provides an automated assessment of basic accessibility issues in addition to search engine
-automation, page performance, and other best practices.
+If you are curious about how we do accessibility CI for this theme, refer to the
+page [](../community/topics/accessibility.md).
-:::{hint}
-Specifically, [foo-software/lighthouse-check-action](https://github.com/foo-software/lighthouse-check-action)
-is run on selected pages from the generated documentation site.
+:::{warning}
+Note that automated testing and extensions such as the ones mentioned above will
+at best catch 30-40% of accessibility issues. They are not a replacement for
+manual testing. Having a perfect score on any of these tools does not mean that
+your site can be used by disabled users. Instead, a good score signals that your
+site follows some best accessibility practices.
:::
diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst
index 050679bee5..43a6e34fcd 100644
--- a/docs/user_guide/extending.rst
+++ b/docs/user_guide/extending.rst
@@ -87,7 +87,9 @@ The title is specified on the same line as the ``.. admonition::`` directive:
Styling with semantic color names
---------------------------------
-You can re-style any admonition to match any of the built-in admonition types using any of the :ref:`theme's semantic color names ` as a class (this is most useful for custom-titled admonitions):
+You can re-style any admonition to match any of the built-in admonition types
+using any of the :ref:`theme's semantic color names ` as a
+class (this is most useful for custom-titled admonitions):
.. begin-example-semantic
.. admonition:: Custom title with "warning" style
diff --git a/docs/user_guide/fonts.rst b/docs/user_guide/fonts.rst
index ee84e29cde..8a29c8e83d 100644
--- a/docs/user_guide/fonts.rst
+++ b/docs/user_guide/fonts.rst
@@ -7,6 +7,9 @@ icon font (the ``.fa-solid, .fa-regular, .fa-brands`` styles, which are used for
This is the only *vendored* font, and otherwise, the theme by default relies on
available system fonts for normal body text and headers.
+For more details on the PyData Sphinx Theme typography and text styles, see the
+:doc:`../community/design-system` section.
+
The default body and header fonts can be changed as follows:
- Using :ref:`custom-css`, you can specify which fonts to use for the body, header,
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 697f321719..b3bc6d7b8e 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -593,4 +593,3 @@ Please find here the full list of keys you can use in the ``html_theme_options``
.. include:: ../../src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf
:code: ini
:class: highlight-ini
-
diff --git a/docs/user_guide/light-dark.rst b/docs/user_guide/light-dark.rst
index 66d6c312ce..389278b6e0 100644
--- a/docs/user_guide/light-dark.rst
+++ b/docs/user_guide/light-dark.rst
@@ -4,7 +4,8 @@
Light and dark themes
=====================
-You can change the major background/foreground colors of this theme using built-in "dark" and "light" modes.
+You can change the major background/foreground colors of this theme using
+built-in "dark" and "light" modes.
These are controlled by a button in the navigation header, with the following options:
- A ``light`` theme with a bright background and dark text / UI elements
@@ -16,7 +17,8 @@ Configure default theme mode
----------------------------
By default, visitors to your documentation will use the theme mode ``auto``.
-This will choose a theme based on the user's system settings, and default to ``light`` if no system setting is found.
+This will choose a theme based on the user's system settings, and default to
+``light`` if no system setting is found.
If you wish to use a different default theme mode, set the ``default_mode`` configuration to one of ``auto``, ``dark``, ``light``.
For example:
diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index 927584aaf8..44cdbf7e41 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -132,14 +132,18 @@ Here are some of the available button-style links, also using semantic colors:
.. note::
`Sphinx Design buttons
- `__
- are actually links, meaning they are rendered in HTML with ```` tags
- instead of ``