Keyboard handlers to open and close mobile sidebars

docs/_extension/component_directive.py

@@ -0,0 +1,98 @@
+"""A directive to generate the list of all the built-in components.
+
+Read the content of the component folder and generate a list of all the components.
+This list will display some informations about the component and a link to the
+GitHub file.
+"""
+import re
+from pathlib import Path
+from typing import Any, Dict, List
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+
+logger = logging.getLogger(__name__)
+
+
+class ComponentListDirective(SphinxDirective):
+    """A directive to generate the list of all the built-in components.
+
+    Read the content of the component folder and generate a list of all the components.
+    This list will display some informations about the component and a link to the
+    GitHub file.
+    """
+
+    name = "component-list"
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self) -> List[nodes.Node]:
+        """Create the list."""
+        # get the list of all th jinja templates
+        # not that to remain compatible with sphinx they are labeled as html files
+        root = Path(__file__).parents[2]
+        component_dir = (
+            root
+            / "src"
+            / "pydata_sphinx_theme"
+            / "theme"
+            / "pydata_sphinx_theme"
+            / "components"
+        )
+        if not component_dir.is_dir():
+            raise FileNotFoundError(
+                f"Could not find component folder at {component_dir}."
+            )
+        components = sorted(component_dir.glob("*.html"))
+
+        # create the list of all the components description using bs4
+        # at the moment we use dummy information
+        docs = []
+        pattern = re.compile(r"(?<={#).*?(?=#})", flags=re.DOTALL)
+        for c in components:
+            comment = pattern.findall(c.read_text())
+            docs.append(comment[0].strip() if comment else "No description available.")
+
+        # get the urls from the github repo latest branch
+        github_url = "https://github.com/pydata/pydata-sphinx-theme/blob/main"
+        urls = [
+            f"{github_url}/{component.relative_to(root)}" for component in components
+        ]
+
+        # build the list of all the components
+        items = []
+        for component, url, doc in zip(components, urls, docs):
+            items.append(
+                nodes.list_item(
+                    "",
+                    nodes.paragraph(
+                        "",
+                        "",
+                        nodes.reference("", component.stem, internal=False, refuri=url),
+                        nodes.Text(f": {doc}"),
+                    ),
+                )
+            )
+
+        return [nodes.bullet_list("", *items)]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add custom configuration to sphinx app.
+
+    Args:
+        app: the Sphinx application
+
+    Returns:
+        the 2 parallel parameters set to ``True``.
+    """
+    app.add_directive("component-list", ComponentListDirective)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/_extension/gallery_directive.py

@@ -75,7 +75,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.warn(f"Could not find grid data at {path_data}.")
+                logger.info(f"Could not find grid data at {path_data}.")
                 nodes.text("No grid data found at {path_data}.")
                 return
             yaml_string = path_data.read_text()
@@ -86,7 +86,6 @@ def run(self) -> List[nodes.Node]:
         # and generate a card item for each of them
         grid_items = []
         for item in safe_load(yaml_string):
-
             # remove parameters that are not needed for the card options
             title = item.pop("title", "")
 

docs/_static/custom.css

@@ -7,15 +7,13 @@
 div.admonition.admonition-olive {
   border-color: hsl(60, 100%, 25%);
 }
-div.admonition.admonition-olive > .admonition-title:before {
+div.admonition.admonition-olive > .admonition-title {
   background-color: hsl(60, 100%, 14%);
+  color: white;
 }
 div.admonition.admonition-olive > .admonition-title:after {
   color: hsl(60, 100%, 25%);
 }
-div.admonition.admonition-olive > .admonition-title {
-  color: white;
-}
 /* end-custom-color */
 
 /* begin-custom-icon/* <your static path>/custom.css */
@@ -30,16 +28,14 @@ div.admonition.admonition-icon > .admonition-title:after {
 div.admonition.admonition-youtube {
   border-color: hsl(0, 100%, 50%); /* YouTube red */
 }
-div.admonition.admonition-youtube > .admonition-title:before {
+div.admonition.admonition-youtube > .admonition-title {
   background-color: hsl(0, 99%, 18%);
+  color: white;
 }
 div.admonition.admonition-youtube > .admonition-title:after {
   color: hsl(0, 100%, 50%);
   content: "\f26c"; /* fa-solid fa-tv */
 }
-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

docs/_static/switcher.json

@@ -4,8 +4,8 @@
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/"
   },
   {
-    "name": "0.14.2 (stable)",
-    "version": "v0.14.2",
+    "name": "0.14.3 (stable)",
+    "version": "v0.14.3",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/",
     "preferred": true
   },

docs/conf.py

@@ -34,6 +34,9 @@
     "sphinx_design",
     "sphinx_copybutton",
     "autoapi.extension",
+    # custom extentions
+    "_extension.gallery_directive",
+    "_extension.component_directive",
     # For extension examples and demos
     "myst_parser",
     "ablog",
@@ -44,10 +47,10 @@
     "sphinx_togglebutton",
     "jupyterlite_sphinx",
     "sphinx_favicon",
-    # custom extentions
-    "_extension.gallery_directive",
 ]
 
+jupyterlite_config = "jupyterlite_config.json"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/examples/gallery.md

@@ -35,7 +35,7 @@ Thanks for your support!
   link: https://fairlearn.org/main/about/
 - title: Feature-engine
   link: https://feature-engine.readthedocs.io/
-- title: idtracker.ai
+- title: idtracker.ai
   link: https://idtracker.ai/
 - title: MegEngine
   link: https://www.megengine.org.cn/doc/stable/en/index.html

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}

docs/jupyterlite_config.json

@@ -0,0 +1,7 @@
+{
+  "LiteBuildConfig": {
+    "Application": {
+      "log_level": 40
+    }
+  }
+}

docs/user_guide/header-links.rst

@@ -145,6 +145,17 @@ Image icons
 
 If you'd like to display an icon image that is not in the FontAwesome icons library,
 you may instead specify a URL or a path to a local image that will be used for the icon.
+You may also use ``.svg`` images as if they were FontAwesome with a little additional setup.
+
+Bitmap image icons
+~~~~~~~~~~~~~~~~~~
+
+For all bitmap image icons such as ``.png``, ``.jpg``, etc., you must specify ``type`` as local.
+
+.. note::
+
+    All icon images with ``"type": "local"`` are inserted into the document using ``<img>`` tags.
+    If you need features specific to objects in the ``svg`` class please see :ref:`svg image icons <svg-image-icons>`
 
 **To display an image on the web**, use ``"type": "url"``, and provide a URL to an image in the ``icon`` value.
 For example:
@@ -188,6 +199,65 @@ For example:
 
    Use ``.svg`` images for a higher-resolution output that behaves similarly across screen sizes.
 
+.. _svg-image-icons:
+
+SVG image icons
+~~~~~~~~~~~~~~~
+
+In order to make use of the full feature set of ``.svg`` images provided by HTML you will need
+to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly straightforward process:
+
+#. Copy the contents of ``custom-icon.js`` - located within the ``docs`` tree - into an appropriate directory of your documentation
+   source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified
+
+   .. code:: javascript
+
+     prefix: "fa-custom",
+     iconName: "pypi",
+     icon: [
+       17.313, // viewBox width
+       19.807, // viewBox height
+       [], // ligature
+       "e001", // unicode codepoint - private use area
+       "m10.383 0.2-3.239 ...", // string definined SVG path
+     ],
+
+
+#. Update the following file contents:
+
+   #.  ``iconName``  to be one of our choosing
+   #.  Change the viewbox height and width to match that of your icon
+   #.  Replace the SVG path string with the path which defines your custom icon
+
+#. Add the relative path from your source directory to the custom javascript file to your ``conf.py``:
+
+   .. code:: python
+
+      html_js_files = [
+         ...
+         "js/pypi-icon.js",
+         ...
+      ]
+
+#. Set up the icon link in the ``html_theme_options`` as a FontAwesome icon:
+
+   .. code:: python
+
+      html_theme_options = [
+         ...
+         "icon_links": [
+            {
+               "name": "PyPI",
+               "url": "https://www.pypi.org",
+               "icon": "fa-custom fa-pypi",
+               "type": "fontawesome",
+            },
+         ],
+         ...
+      ]
+
+That's it, your icon will now be inserted with the ``<svg>`` tag and not ``<img>``! You can reference your custom FontAwesome icon in CSS using ``fa-<custom-name>``.
+
 .. _icon-link-shortcuts:
 
 Icon Link Shortcuts

docs/user_guide/index.md

@@ -74,5 +74,6 @@ accessibility
 analytics
 static_assets
 performance
+warnings
 readthedocs
 ```

docs/user_guide/layout.rst

@@ -518,29 +518,12 @@ Below is a list of built-in templates that you can insert into any section.
 Note that some of them may have CSS rules that assume a specific section (and
 will be named accordingly).
 
-.. refer to files in: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/
-
-- ``breadcrumbs.html``
-- ``copyright.html``
-- ``edit-this-page.html``
-- ``footer-article/prev-next.html``
-- ``icon-links.html``
-- ``last-updated.html``
-- ``navbar-icon-links.html``
-- ``navbar-logo.html``
-- ``navbar-nav.html``
-- ``page-toc.html``
-- ``searchbox.html``
-- ``search-button.html``
-- ``search-field.html``
-- ``sidebar-ethical-ads.html``
-- ``sidebar-nav-bs.html``
-- ``sourcelink.html``
-- ``sphinx-version.html``
-- ``theme-switcher.html``
-- ``version-switcher.html``
-- ``indices.html``
-- ``theme-version.html``
+.. note::
+
+    When adding/changing/overwritting a component, the ".html" suffix is optional.
+    That's why all of them are displayed without it in the following list.
+
+.. component-list::
 
 
 Add your own HTML templates to theme sections

docs/user_guide/theme-elements.md

@@ -48,7 +48,7 @@ You can add a link to equations like the one above {eq}`My label` and {eq}`My la
 
 ## Code blocks
 
-Code block styling is inspired by [GitHub's code block style](https://primer.style/css/components/markdown) and also has support for Code Block captions/titles.
+Code block styling is inspired by [GitHub's code block style](https://primer.style/components/markdown) and also has support for Code Block captions/titles.
 See [the Sphinx documentation on code blocks](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) for more information.
 
 ```python

docs/user_guide/warnings.rst

@@ -0,0 +1,15 @@
+
+Theme changes, deprecations, and warnings
+=========================================
+
+Generally speaking, the best source of information about changes to the theme will be the release changelog.
+We try to avoid raising warnings within theme code, which means sometimes the theme will change (perhaps significantly) without deprecation warnings or other alerts.
+Still, we occasionally do warn about things like (upcoming) changes to the theme's default config values.
+If you prefer *not* to receive such warnings, there is a config value to suppress them:
+
+.. code-block::
+    :caption: conf.py
+
+    html_theme_options = {
+        "surface_warnings": False
+    }

noxfile.py

@@ -77,6 +77,8 @@ def docs(session: nox.Session) -> None:
         "-v",
         "-w",
         "warnings.txt",
+        # suppress Py3.11's new "can't debug frozen modules" warning
+        env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"),
     )
     session.run("python", "tests/utils/check_warnings.py")
 
@@ -92,7 +94,13 @@ def docs_live(session: nox.Session) -> None:
             "sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b"
         )
     session.run(
-        "stb", "serve", "docs", "--open-browser", "--re-ignore=locale|api|_build"
+        "stb",
+        "serve",
+        "docs",
+        "--open-browser",
+        r"--re-ignore=locale|api|_build|\.jupyterlite\.doit\.db",
+        # suppress Py3.11's new "can't debug frozen modules" warning
+        env=dict(PYDEVD_DISABLE_FILE_VALIDATION="1"),
     )