update feature focus (#1569)

* docs: add instructions for custom SVG icons (#1490) * docs: add instructions for custom SVG icons * docs: minor tweaks in SVG icon instructions * docs: some more tweaks to SVG icon instructions * Update docs/user_guide/header-links.rst Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * Change literalinclude to code-block in header links * Update docs/user_guide/header-links.rst Co-authored-by: Daniel McCloy <dan@mccloy.info> * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst --------- Co-authored-by: tgresavage <thomas.gresavage.ext@afresearchlab.com> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: make table background transparent (#1546) * fix: make table background transparent * fix: make table background transparent * fix: add color-theme option to html tag (#1536) * Silence warnings (#1542) * avoid webpack warning during asset compile * avoid frozen modules warning during import * try to make jupyterlite quieter * add config option to silence warnings * fix tests * add docs * hide conditional warning logic in utils * bump: 0.14.2 → 0.14.3 * chore: back to dev * docs: add the list of component using a directive (#1476) * fix: create the component list automatically * fix: read the first comment as documentation * docs: add disclaimer on .html suffix * docs: document every component with a simple one liner * fix: use regex to identify comments * update component branch (#15) * Change default logo alt text (#1472) * Default logo alt text only if no extra text * change default logo * use docstitle as default logo alt text * update docs to reflect change * Apply suggestions from code review Co-authored-by: Daniel McCloy <dan@mccloy.info> * use string formatting operator * Update docs/user_guide/branding.rst * docs fixes * Update docs/user_guide/branding.rst * add test * Update pyproject.toml * revert to original --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * chore(i18n) catalan (#1488) i18n: Translate sphinx.po in ca 100% translated source file: 'sphinx.po' on 'ca'. Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> * Build(deps): Bump postcss and css-loader (#1494) Bumps [postcss](https://github.com/postcss/postcss) to 8.4.31 and updates ancestor dependency [css-loader](https://github.com/webpack-contrib/css-loader). These dependencies need to be updated together. Updates `postcss` from 8.4.21 to 8.4.31 - [Release notes](https://github.com/postcss/postcss/releases) - [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md) - [Commits](postcss/postcss@8.4.21...8.4.31) Updates `css-loader` from 3.6.0 to 6.8.1 - [Release notes](https://github.com/webpack-contrib/css-loader/releases) - [Changelog](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md) - [Commits](webpack-contrib/css-loader@v3.6.0...v6.8.1) --- updated-dependencies: - dependency-name: postcss dependency-type: indirect - dependency-name: css-loader dependency-type: direct:development ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Revert "Build(deps): Bump postcss and css-loader" (#1509) Revert "Build(deps): Bump postcss and css-loader (#1494)" This reverts commit 185a37a. * Update pst docs buttons (#1502) * call them button-links * copy edit * docs: link back to GitHub from PyPI metadata (#1504) This will add a "Source" link in the PyPI page. * navigation_with_keys = False (#1503) * navigation_with_keys = False * None -> False * Apply suggestions from code review --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: convert "stable" to actual version number (#1512) * convert "stable" to actual version number * fix tests re: navigation_with_keys * try bumping autoapi * refactor: use nbsphinx as the default execution lib (#1482) * refactor: use nbsphinx as the default execution lib * add nbstripout to the pre-commits' * add pandoc to the readthedocs deps * refactor: clean the notebook * move the example to the correct folder * fix: solve link issue * install pandoc in the test environment * fix: display of large table in executed cells * avoid Userwarnings from matplotlib * hide the matplotlib wrning management cell * Update readthedocs.yml * build: use pandoc_binary to install pandoc * docs: add reference to pandoc in the setup * update docs * remove pypandoc_binary * Update pyproject.toml Co-authored-by: gabalafou <gabriel@fouasnon.com> * ci: use back setup-pandoc * Trigger CI build --------- Co-authored-by: Gabriel Fouasnon <gabriel@fouasnon.com> * BUG - Clear alt_text in conf.py (#1471) * comment out alt_text in conf.py * set alt_text to empty string * remove alt_text from conf.py * fix: use 12rambau fork until it's merged with nikeee repo (#1517) * deps: drop support for Sphinx 5 (#1516) * remove ref to myst-nb * update minimal supported version of sphinx * Fix: (webpack.config.js) css-loader API change (#1508) * Fix: (webpack.config.js) css-loader API change The build was broken in <https://github.com/pydata/pydata-sphinx-theme/commit/185a37aa36820f77bffa4c87a772092e9e7cc380>/<https://github.com/pydata/pydata-sphinx-theme/pull/1494>. This change fixes the build, and it seems to be in accordance with the current API as described at <https://github.com/webpack-contrib/css-loader/blob/c6f36cf91ac61743a70e81cfb077faa0f8730ebe/README.md#boolean>. Closes <#1507>. * dedup * restore version bump --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * Fix duplicate HTML IDs (#1425) * Fix duplicate HTML IDs * fix tests * Do not animate the version admonitions colors. (#1424) Otherwise a delay has to be added to the accessibility color contrast checks, to wait for the colors to fully transition. * BUG - Remove redundant ARIA in breadcrumb navigation (#1426) * style(i18n): French Typo fixed (#1430) * Add the ability to add a center section to the footer (#1432) * Add a center section for the footer * Add docs for footer_center * Add a test site for the center footer * test it in our own docs * remove new test site * add footer test --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * Build(deps): Bump actions/checkout from 3 to 4 (#1433) Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Add dropdown_text argument to generate_header_nav_html (#1423) * Add dropdown_text argument to generate_header_nav_html * Add a test, fix typo in theme.conf and remove header_dropdown_text from docs/conf.py * fixed? --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: rollback ref and Id changes (#1438) * bump: version 0.13.3 → 0.14.0 (#1440) * bump version * update version switcher * back to dev * fix: change the z-index of the dropdown (#1442) In order to be on top of the primary sidebar on small screens. * fix: set the same background for dark/light (#1443) * fix: set the same background for dark/light et the same background color for all state of the search field. It is currently only applied when hovered * fix: wrong css selector * Update src/pydata_sphinx_theme/assets/styles/components/_search.scss * Update src/pydata_sphinx_theme/assets/styles/components/_search.scss * Fix duplicate HTML IDs * fix tests * unique_html_id * backwards-compat generate_header_nav_html * feedback review * update fixture * ughhhh...caching * code cleanup * fix test snapshot * put comment inside def --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * chore: build the devcontainer automatically in codespace (#1483) * chore: build the devcontainer automaticallyin codespace * refactor: lint * add pandoc to the environment * Fix font color in search input box (#1524) * Fix color * Use --pst-color-text-base * docs: add DecentralChain (#1528) Co-authored-by: jourlez <josuecr.288@gmail.com> * Updates for file src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po in ru [Manual Sync] (#1527) i18n: Translate sphinx.po in ru [Manual Sync] 96% of minimum 20% translated source file: 'sphinx.po' on 'ru'. Sync of partially translated files: untranslated content is included with an empty translation or source language content depending on file format Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> * ignore transient errors in windows build CI (#1520) * use warning list * clean up notebook * refactor to pass on all platforms? * simplify * fix logic * iterate backwards * fix plaform detection? also don't log unnecessarily�[H * ignore empty string warnings * remove notebook metawarning * Revert "remove notebook metawarning" This reverts commit 42f4672. * try again * debug the mysterious empty warning * escape color codes * import * triage by intermittency, not by platform; better var names * simplify * fix list.remove * undo what I broke * Update tests/utils/check_warnings.py * refactor: remove extention on component set-up (#1529) * use event.key for search shortcut (#1525) * use event.key for search shortcut * suggestions from review * caps lock --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> * fix: use a directive instead of raw html * fix: make links externals * fix: set reference in paragraphs * fix: missing parameter * fix: use the stem for the component name * refactor: remove never used variables * standardize component descriptions --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> * fix: primer link in docs (#1556) * docs: add data-content (#1559) Reproduce the change made in Sphinx 7 sphinx-doc/sphinx@8e730ae#diff-a5066e933cbf65adc46e0d1ab9a0b44e0a53ca64cc95dca7e6aa902aed6bd468R105 * Obviate background-from-color-variable (#1558) * Obviate background-from-color-variable * backwards compatibility --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gresavage <tomgresavage@gmail.com> Co-authored-by: tgresavage <thomas.gresavage.ext@afresearchlab.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu>
pydata · Nov 20, 2023 · e054da1 · e054da1
1 parent 9803c5e
commit e054da1
Show file tree

Hide file tree

Showing 52 changed files with 451 additions and 1,946 deletions.
diff --git a/docs/_extension/component_directive.py b/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,
+    }
diff --git a/docs/_extension/gallery_directive.py b/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", "")
 

diff --git a/docs/_static/custom.css b/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

diff --git a/docs/_static/switcher.json b/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
   },

diff --git a/docs/conf.py b/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"]
 

diff --git a/docs/jupyterlite_config.json b/docs/jupyterlite_config.json
@@ -0,0 +1,7 @@
+{
+  "LiteBuildConfig": {
+    "Application": {
+      "log_level": 40
+    }
+  }
+}
diff --git a/docs/user_guide/header-links.rst b/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

diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
@@ -74,5 +74,6 @@ accessibility
 analytics
 static_assets
 performance
+warnings
 readthedocs
 ```
diff --git a/docs/user_guide/layout.rst b/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

diff --git a/docs/user_guide/theme-elements.md b/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

diff --git a/docs/user_guide/warnings.rst b/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
+    }
diff --git a/noxfile.py b/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"),
     )