diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index cbf32afd8..dc5d0011b 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -52,7 +52,17 @@ jobs:
# Build the docs
- name: Build docs to store
run: |
- sphinx-build -b html docs/ docs/_build/html -W --keep-going
+ 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'
+ shell: python
+ run: |
+ from pathlib import Path
+ text = Path("./warnings.txt").read_text().strip()
+ print("\n=== Sphinx Warnings ===\n\n" + text) # Print just for reference so we can look at the logs
+ unexpected = [ii for ii in text.split("\n") if "kitchen-sink" not in ii]
+ assert len(unexpected) == 0
# Run tests under coverage
- name: Run the tests
@@ -86,28 +96,15 @@ jobs:
cache: "pip"
cache-dependency-path: "pyproject.toml"
- - name: Set up Node/yarn
- uses: actions/setup-node@v1
- with:
- node-version: "16.x"
-
- - name: Cache node_modules
- uses: actions/cache@v2
- with:
- path: "node_modules"
- key: |
- ${{ runner.os }}-node-modules-${{ hashFiles('package.json') }}
-
- name: Install dependencies
run: |
python -m pip install --upgrade pip wheel setuptools
python -m pip install -e .[coverage]
- yarn --frozen-lockfile
# Build the docs
- name: Build docs to store
run: |
- sphinx-build -b html docs/ docs/_build/html -W --keep-going
+ sphinx-build -b html docs/ docs/_build/html
# Serve the docs and wait to be ready
- name: Serve the built site
@@ -128,7 +125,8 @@ jobs:
urls: >-
${{ env.URL }}/index.html,
${{ env.URL }}/demo/api.html,
- ${{ env.URL }}/demo/demo.html,
+ ${{ env.URL }}/demo/kitchen-sink/paragraph-markup.html,
+ ${{ env.URL }}/demo/kitchen-sink/lists-and-tables.html,
${{ env.URL }}/demo/example_pandas.html,
${{ env.URL }}/user_guide/accessibility.html
outputDirectory: /tmp/lighthouse/lighthouse-${{ github.run_number }}
diff --git a/docs/conf.py b/docs/conf.py
index 6846c3215..bed6b6a87 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -120,6 +120,7 @@
"sidebar-nav-bs",
"custom-template",
], # This ensures we test for custom sidebars
+ "demo/no-sidebar": [], # Test what page looks like with no sidebar items
}
diff --git a/docs/contribute/topics.md b/docs/contribute/topics.md
index 8909f3d2b..c09ea2cf8 100644
--- a/docs/contribute/topics.md
+++ b/docs/contribute/topics.md
@@ -223,3 +223,22 @@ is required. The steps are roughly:
- remove references to the font being replaced/removed, if applicable
- see the `font-awesome` sections of this configuration to see what the end-result configuration looks like.
- re-compile the theme's assets: `nox -s compile`
+
+## Update our kitchen sink documents
+
+The [kitchen sink reference](../demo/kitchen-sink/index.rst) is for demonstrating as much syntax and style for Sphinx builds as possible.
+It is copied directly from the [`sphinx-themes.org` documentation](https://sphinx-themes.org/) so that we use standardized reference docs compared with other communities.
+The source files for these pages are stored [in the `sphinx-themes.org` repository](https://github.com/sphinx-themes/sphinx-themes.org/raw/master/sample-docs/kitchen-sink/).
+
+If you'd like to update our local files with any changes that have been made to the `sphinx-themes.org` files, simply copy/paste those changes into our local files and make a commit.
+
+Here's a list of our pages and where they come from in `sphinx-themes.org`:
+
+- [`index.rst`](../demo/kitchen-sink/index.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/index.rst))
+- [`api.rst`](../demo/kitchen-sink/api.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/api.rst))
+- [`lists-and-tables.rst`](../demo/kitchen-sink/lists-and-tables.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/lists-and-tables.rst))
+- [`paragraph-markup.rst`](../demo/kitchen-sink/paragraph-markup.rst) ([source](https://github.com/sphinx-themes/sphinx-themes.org/blob/master/sample-docs/kitchen-sink/paragraph-markup.rst))
+
+:::{note}
+To demonstrate extra styles and syntax that is not in the Kitchen sink, use the [Theme Elements reference](../demo/theme-elements.md).
+:::
diff --git a/docs/demo/api.rst b/docs/demo/api.rst
index 291c8a0e5..64cc5bef3 100644
--- a/docs/demo/api.rst
+++ b/docs/demo/api.rst
@@ -1,6 +1,6 @@
-***************************************
-API documentation and generated content
-***************************************
+************************************************
+Advanced API documentation and generated content
+************************************************
This page contains general code elements that are common
for package documentation.
diff --git a/docs/demo/index.rst b/docs/demo/index.rst
index 204dbaf41..ede3c1b8b 100644
--- a/docs/demo/index.rst
+++ b/docs/demo/index.rst
@@ -10,24 +10,20 @@ the left sidebar to see how various elements look on this theme.
:maxdepth: 2
:caption: Demo Documentation
- structure
- demo
+ kitchen-sink/index
+ theme-elements
api
- lists_tables
- markdown
example_pandas
- mult_headers
- subpages/index
- subpages2/index
Link to an external site
.. toctree::
:maxdepth: 3
:numbered:
- :caption: This is an incredibly long caption for a long menu
-
- long
+ :caption: This is an incredibly long caption for a long menu. Here are some more subpages to show off deep nested pages.
+ no-sidebar
+ mult_headers
+ subpages/index
.. meta::
:description lang=en:
diff --git a/docs/demo/kitchen-sink/api.rst b/docs/demo/kitchen-sink/api.rst
new file mode 100644
index 000000000..989941b46
--- /dev/null
+++ b/docs/demo/kitchen-sink/api.rst
@@ -0,0 +1,10 @@
+.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
+*****************
+API documentation
+*****************
+
+``asyncio``
+===========
+
+.. automodule:: asyncio
+ :members: run, gather, AbstractEventLoop
diff --git a/docs/demo/kitchen-sink/index.rst b/docs/demo/kitchen-sink/index.rst
new file mode 100644
index 000000000..552ca51f8
--- /dev/null
+++ b/docs/demo/kitchen-sink/index.rst
@@ -0,0 +1,12 @@
+.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
+============
+Kitchen Sink
+============
+
+This section showcases the various elements that Sphinx supports out-of-the-box.
+
+.. toctree::
+
+ paragraph-markup
+ api
+ lists-and-tables
diff --git a/docs/demo/lists_tables.rst b/docs/demo/kitchen-sink/lists-and-tables.rst
similarity index 84%
rename from docs/demo/lists_tables.rst
rename to docs/demo/kitchen-sink/lists-and-tables.rst
index 2349c2a4b..097bb8aca 100644
--- a/docs/demo/lists_tables.rst
+++ b/docs/demo/kitchen-sink/lists-and-tables.rst
@@ -1,4 +1,4 @@
-
+.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
**************
Lists & Tables
**************
@@ -47,6 +47,18 @@ Term : classifier
Term
Definition
+I have no clue why the definition list below is classified as a different style
+of definition list than the one above.
+
+Is it the spaces in the term?
+ Maybe it was the multiple line paragraph
+ in the line below that caused this?
+
+Is it the paragraph above the list maybe?
+ I guess a lot of these lists don't have leading paragraphs?
+
+Is it everything all at once?
+ Who knows?!
Option Lists
------------
@@ -116,6 +128,28 @@ Field list
Bullet Lists
------------
+..
+ Docutils supports two types of lists, "simple" and "complex". Complex lists
+ have item margins, simple lists do not.
+ https://docutils.sourceforge.io/sandbox/html4strict/data/simple-lists.html
+
+Simple
+^^^^^^
+
+- A simple list.
+- There are no margins between list items.
+- Simple lists do not contain multiple paragraphs. That's a complex list.
+- In the case of a nested list
+
+ - There are no margins between elements
+
+ - Still no margins
+
+ - Still no margins
+
+Complex
+^^^^^^^
+
- A bullet list
+ Nested bullet list.
@@ -136,6 +170,13 @@ Bullet Lists
- ``inline literall``
- ``inline literall``
- ``inline literall``
+- This item has multiple paragraphs.
+
+ This item has multiple paragraphs.
+- This item has multiple paragraphs.
+
+ This item has multiple paragraphs.
+
Second list level
^^^^^^^^^^^^^^^^^
@@ -151,13 +192,18 @@ Second list level
heh heh. child. try to beat this embed:
- .. literalinclude:: test_py_module/test.py
- :language: python
+ .. literalinclude:: api.rst
+ :language: rst
:linenos:
- :lines: 1-10
+
- and another. `yahoo `_
- `yahoo `_
- ``hi``
+- how about an admonition?
+
+ .. note::
+ This is a note nested in a list.
+
- and hehe
But deeper down the rabbit hole
@@ -192,11 +238,11 @@ Hlists
.. hlist::
:columns: 2
- - .. figure:: static/yi_jing_01_chien.jpg
+ - .. figure:: https://source.unsplash.com/200x200/daily?cute+animals
This is a short caption for a figure.
- - .. figure:: static/yi_jing_01_chien.jpg
+ - .. figure:: https://source.unsplash.com/200x200/daily?cute+animals
This is a long caption for a figure. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Donec porttitor dolor in odio posuere, vitae ornare libero mattis. In lobortis justo vestibulum nibh aliquet, non.
@@ -290,15 +336,11 @@ List Tables
.. list-table:: This is a list table with images in it.
- * - .. figure:: static/yi_jing_01_chien.jpg
+ * - .. figure:: https://source.unsplash.com/200x200/daily?cute+animals
This is a short caption for a figure.
- - .. figure:: static/yi_jing_01_chien.jpg
+ - .. figure:: https://source.unsplash.com/200x200/daily?cute+animals
This is a long caption for a figure. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Donec porttitor dolor in odio posuere, vitae ornare libero mattis. In lobortis justo vestibulum nibh aliquet, non.
-
-.. meta::
- :description lang=en:
- Examples of table features in pydata-sphinx-theme.
diff --git a/docs/demo/demo.rst b/docs/demo/kitchen-sink/paragraph-markup.rst
similarity index 81%
rename from docs/demo/demo.rst
rename to docs/demo/kitchen-sink/paragraph-markup.rst
index ecd4fc930..26ddb06e5 100644
--- a/docs/demo/demo.rst
+++ b/docs/demo/kitchen-sink/paragraph-markup.rst
@@ -1,9 +1,10 @@
+.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
.. This is a comment. Note how any initial comments are moved by
transforms to after the document title, subtitle, and docinfo.
.. demo.rst from: http://docutils.sourceforge.net/docs/user/rst/demo.txt
-.. |EXAMPLE| image:: static/yi_jing_01_chien.jpg
+.. |EXAMPLE| image:: https://source.unsplash.com/200x200/daily?cute+animals
:width: 1em
**********************
@@ -19,7 +20,7 @@ external hyperlinks with embedded URIs (`Python web site
(manually numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered [#label]_, or symbolic [*]_),
citation references ([12]_), substitution references (|example|), and _`inline hyperlink targets`
(see Targets_ below for a reference back to here). Character-level inline markup is also possible
-(although exceedingly ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by problematic
+(although exceedingly ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by |problematic|
text (generated by processing errors; this one is intentional).
Also with ``sphinx.ext.autodoc``, which I use in the demo, I can link to :class:`test_py_module.test.Foo`.
@@ -200,7 +201,7 @@ Sidebar
.. sidebar:: Ch'ien / The Creative
- .. image:: static/yi_jing_01_chien.jpg
+ .. image:: https://source.unsplash.com/200x200/daily?cute+animals
*Above* CH'IEN THE CREATIVE, HEAVEN
@@ -225,11 +226,11 @@ Code with Sidebar
With a sidebar on the right.
-.. literalinclude:: test_py_module/test.py
- :language: python
+.. literalinclude:: api.rst
+ :language: rst
:caption: Literal includes can also have captions.
:linenos:
- :lines: 1-40
+ :lines: 5-15
References
==========
@@ -256,16 +257,21 @@ Footnotes
.. [*] This footnote shows the next symbol in the sequence.
+.. [4] Here's an unreferenced footnote, with a reference to a
+ nonexistent footnote: [5]_.
+
Citations
---------
+.. [11] This is the citation I made, let's make this extremely long so that we can tell that it doesn't follow the normal responsive table stuff.
+
.. [12] This citation has some ``code blocks`` in it, maybe some **bold** and
*italics* too. Heck, lets put a link to a meta citation [13]_ too.
.. [13] This citation will have two backlinks.
-Here's a reference to the above, [12]_.
+Here's a reference to the above, [12]_, and a [nonexistent]_ citation.
Here is another type of citation: `citation`
@@ -295,7 +301,7 @@ A reference can be found under `Inline Markup`_, above. `Inline
hyperlink targets`_ are also possible.
Section headers are implicit targets, referred to by name. See
-Targets_, which is a subsection of Body Elements.
+Targets_, which is a subsection of `Body Elements`_.
Explicit external targets are interpolated into references such as "Python_".
@@ -306,17 +312,18 @@ refer to the Targets_ section.
__ Targets_
+Here's a `hyperlink reference without a target`_, which generates an error.
Directives
==========
-Contents
---------
+.. contents::
+ :local:
-.. contents:: :local:
-
-These are just a sample of the many reStructuredText Directives. For others, please see:
+Above mini table of contents is generated by the ``.. contents::`` directive.
+It and all the other directives presented here are just a sample of the many
+reStructuredText Directives. For others, please see:
http://docutils.sourceforge.net/docs/ref/rst/directives.html.
@@ -335,30 +342,13 @@ Images
An image directive (also clickable -- a hyperlink reference):
-.. image:: static/yi_jing_01_chien.jpg
+.. image:: https://source.unsplash.com/200x200/daily?cute+animals
:target: directives_
-A larger image, with no options:
-
-.. image:: static/Sphinx-and-the-Pyramids-of-Ghiza-by-Facchinelli.png
-
-
-With a fixed with of 600px and centered:
-
-.. image:: static/Sphinx-and-the-Pyramids-of-Ghiza-by-Facchinelli.png
- :width: 600px
- :align: center
-
-And using the img-fluid class:
-
-.. image:: static/Sphinx-and-the-Pyramids-of-Ghiza-by-Facchinelli.png
- :class: img-fluid
-
-
Figures
^^^^^^^
-.. figure:: static/yi_jing_01_chien.jpg
+.. figure:: https://source.unsplash.com/200x200/daily?cute+animals
:alt: reStructuredText, the markup syntax
A figure is an image with a caption and/or a legend:
@@ -375,7 +365,7 @@ Figures
A figure directive with center alignment
-.. figure:: static/yi_jing_01_chien.jpg
+.. figure:: https://source.unsplash.com/200x200/daily?cute+animals
:align: center
This caption should be centered.
@@ -409,13 +399,6 @@ Admonitions
Equations within a note:
:math:`G_{\mu\nu} = 8 \pi G (T_{\mu\nu} + \rho_\Lambda g_{\mu\nu})`.
-.. Note:: Lists in admonitions.
-
- 1. Here's a list item
- 2. And another list item
-
- They should be in-line with the text around them!
-
.. Tip:: 15% if the service is good.
+---------+
@@ -431,53 +414,24 @@ Admonitions
.. WARNING:: Strong prose may provoke extreme mental exertion.
Reader discretion is strongly advised.
-.. note::
-
- .. tip:: You can embed admonitions!
-
.. admonition:: And, by the way...
You can make up your own admonition too.
-.. admonition:: If you add a class flag, it will be styled
- :class: warning
-
- For example, this admonition block uses the following code:
-
- .. code-block::
-
- .. admonition:: If you add a class flag, it will be styled
- :class: warning
-
- Here are a list of classes you can try:
-
- .. code-block::
-
- note
- important
- tip
- attention
- caution
- warning
- danger
- error
- hint
+Deprecations
+------------
-Version change
---------------
+.. versionadded:: v0.1
-You can write in your documentation when something has been changed,
-added or deprecated from one version to another.
+ This is a version added message.
-.. versionadded:: 0.1.1
- Something is new, use it from now.
+.. versionchanged:: v0.2
-.. versionchanged:: 0.1.1
- Something is modified, check your version number.
+ This is a version changed message.
-.. deprecated:: 0.1.1
- Something is deprecated, use something else instead.
+.. deprecated:: v0.3
+ This is a deprecation message.
Topics, Sidebars, and Rubrics
-----------------------------
@@ -532,40 +486,4 @@ with the "compound" directive.
Download Links
==============
-:download:`This long long long long long long long long long long long long long long long download link should be blue, normal weight text with a leading icon, and should wrap white-spaces `
-
-HTML
-====
-
-The HTML below shouldn't display, but it uses RequireJS to make sure that all
-works as expected. If the widgets don't show up, RequireJS may be broken.
-
-.. jupyter-execute::
-
- import plotly.io as pio
- import plotly.express as px
- import plotly.offline as py
-
- pio.renderers.default = "notebook"
-
- df = px.data.iris()
- fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", size="sepal_length")
- fig
-
-And here we demonstrate ``xarray`` to ensure that it shows up properly.
-
-.. jupyter-execute::
-
- import xarray as xr
- import numpy as np
- data = xr.DataArray(
- np.random.randn(2, 3),
- dims=("x", "y"),
- coords={"x": [10, 20]}, attrs={"foo": "bar"}
- )
- data
-
-
-.. meta::
- :description lang=en:
- A demo of many output features of pydata-sphinx-theme.
+:download:`This long long long long long long long long long long long long long long long download link should be blue, normal weight text with a leading icon, and should wrap white-spaces `
diff --git a/docs/demo/long.rst b/docs/demo/long.rst
deleted file mode 100644
index d38f63242..000000000
--- a/docs/demo/long.rst
+++ /dev/null
@@ -1,219 +0,0 @@
-
-***************
-Long Sticky Nav
-***************
-
-.. contents:: Table of Contents
-
-This section demonstrates how the 'sticky_navigation' setting behaves when the menu is very long.
-When this section is selected, it will make the menu and the main area scroll when you are at the top of the page.
-
-
-Example Menu 1
-==============
-
-Just a place holder...
-
-
-Example Menu 2
-==============
-
-Just a place holder...
-
-
-Example Menu 3
-==============
-
-Just a place holder...
-
-
-Example Menu 4
-==============
-
-Just a place holder...
-
-
-Example Menu 5
-==============
-
-Just a place holder...
-
-
-Example Menu 6
-==============
-
-Just a place holder...
-
-
-Example Menu 7
-==============
-
-Just a place holder...
-
-
-Example Menu 8
-==============
-
-Just a place holder...
-
-
-Example Menu 9
-==============
-
-Just a place holder...
-
-
-Example Menu 10
-===============
-
-Just a place holder...
-
-
-Example Menu 11
-===============
-
-Just a place holder...
-
-
-Example Menu 12
-===============
-
-Just a place holder...
-
-
-Example Menu 13
-===============
-
-Just a place holder...
-
-
-Example Menu 14
-===============
-
-Just a place holder...
-
-
-Example Menu 15
-===============
-
-Just a place holder...
-
-
-Example Menu 16
-===============
-
-Just a place holder...
-
-
-Example Menu 17
-===============
-
-Just a place holder...
-
-
-Example Menu 18
-===============
-
-Just a place holder...
-
-
-Example Menu 19
-===============
-
-Just a place holder...
-
-
-Example Menu 20
-===============
-
-Just a place holder...
-
-Example Submenu 1
-=================
-
-Just a place holder...
-
-Submenu 1
----------
-
-Just a place holder...
-
-Subsubmenu 1
-^^^^^^^^^^^^
-
-Just a place holder...
-
-Subsubmenu 2
-^^^^^^^^^^^^
-
-Just a place holder...
-
-Submenu 2
----------
-
-Just a place holder...
-
-Subsubmenu 1
-^^^^^^^^^^^^
-
-Just a place holder...
-
-Submenu 3
----------
-
-Just a place holder...
-
-Submenu 4
----------
-
-Just a place holder...
-
-Submenu 5
----------
-
-Just a place holder...
-
-Example Submenu 2
-=================
-
-Just a place holder...
-
-Submenu 1
----------
-
-Just a place holder...
-
-Subsubmenu 1
-^^^^^^^^^^^^
-
-Just a place holder...
-
-Submenu 2
----------
-
-Just a place holder...
-
-Subsubmenu 1
-^^^^^^^^^^^^
-
-Just a place holder...
-
-Submenu 3
----------
-
-Just a place holder...
-
-Submenu 4
----------
-
-Just a place holder...
-
-Submenu 5
----------
-
-Just a place holder...
-
-
-.. meta::
- :description lang=en:
- Examples of long submenus in pydata-sphinx-theme.
diff --git a/docs/demo/markdown.md b/docs/demo/markdown.md
deleted file mode 100644
index b5a959694..000000000
--- a/docs/demo/markdown.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Markdown syntax
-
-Sphinx can also generate pages from Markdown, using the [MyST Parser](https://myst-parser.readthedocs.io).
-This page shows a few markdown-specific pieces of syntax.
-For a description of other markdown syntax that you can use with Sphinx, see [the `myst-parser` reference](https://myst-parser.readthedocs.io/en/latest/syntax/reference.html).
-
-## Horizontal rules
-
-Here's a horizontal rule:
-
----
-
-It separates major sections of content.
-
-## Footnotes
-
-Here's a footnote [^myfootnote]. And it should show up at the bottom!
-
-[^myfootnote]: Here's the text for the footnote!
-
-## Tables
-
-| Syntax | Description | Test Text |
-| :-------- | :---------: | ----------: |
-| Header | Title | Here's this |
-| Paragraph | Text | And more |
diff --git a/docs/demo/no-sidebar.md b/docs/demo/no-sidebar.md
new file mode 100644
index 000000000..f98ce702f
--- /dev/null
+++ b/docs/demo/no-sidebar.md
@@ -0,0 +1,11 @@
+# Test of no sidebar
+
+This page shows off what the documentation looks like when you explicitly tell Sphinx not to include any sidebars via the following configuration:
+
+```python
+html_sidebars = {
+ "path/to/page": [],
+}
+```
+
+The left sidebar should be entirely gone, and the main content should expand slightly to make up the extra space.
diff --git a/docs/demo/structure.rst b/docs/demo/structure.rst
deleted file mode 100644
index 9ac00a710..000000000
--- a/docs/demo/structure.rst
+++ /dev/null
@@ -1,105 +0,0 @@
-
-*******************
-Structural Elements
-*******************
-
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,
-finibus dictum velit. Ut eu efficitur arcu, id aliquam erat. In sit amet diam gravida, imperdiet tellus eu,
-gravida nisl. Praesent aliquet odio eget libero elementum, quis rhoncus tellus tincidunt.
-Suspendisse quis volutpat ipsum. Sed lobortis scelerisque tristique. Aenean condimentum risus tellus,
-quis accumsan ipsum laoreet ut. Integer porttitor maximus suscipit. Mauris in posuere sapien.
-Aliquam accumsan feugiat ligula, nec fringilla libero commodo sed. Proin et erat pharetra.
-
----------
-
-Etiam turpis ante, luctus sed velit tristique, finibus volutpat dui. Nam sagittis vel ante nec malesuada.
-Praesent dignissim mi nec ornare elementum. Nunc eu augue vel sem dignissim cursus sed et nulla.
-Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.
-Pellentesque dictum dui sem, non placerat tortor rhoncus in. Sed placerat nulla at rhoncus iaculis.
-
-Document Section
-================
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed condimentum nulla vel neque venenatis,
-nec placerat lorem placerat. Cras purus eros, gravida vitae tincidunt id, vehicula nec nulla.
-Fusce aliquet auctor cursus. Phasellus ex neque, vestibulum non est vitae, viverra fringilla tortor.
-Donec vestibulum convallis justo, a faucibus lorem vulputate vel. Aliquam cursus odio eu felis sodales aliquet.
-Aliquam erat volutpat. Maecenas eget dictum mauris. Suspendisse arcu eros, condimentum eget risus sed,
-luctus efficitur arcu. Cras ut dictum mi. Nulla congue interdum lorem, semper semper enim commodo nec.
-
-Document Subsection
--------------------
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam efficitur in eros et blandit. Nunc maximus,
-nisl at auctor vestibulum, justo ex sollicitudin ligula, id faucibus urna orci tristique nisl.
-Duis auctor rutrum orci, in ornare lacus condimentum quis. Quisque arcu velit, facilisis quis interdum ac,
-hendrerit auctor mauris. Curabitur urna nibh, porttitor at ante sit amet, vestibulum interdum dolor.
-Duis dictum elit orci, tincidunt imperdiet sem pellentesque et. In vehicula pellentesque varius.
-Phasellus a turpis sollicitudin, bibendum massa et, imperdiet neque. Integer quis sapien in magna rutrum bibendum.
-Integer cursus ex sed magna vehicula finibus. Proin tempus orci quis dolor tempus, nec condimentum odio vestibulum.
-Etiam efficitur sollicitudin libero, tincidunt volutpat ligula interdum sed.
-
-Document Subsubsection
-^^^^^^^^^^^^^^^^^^^^^^
-
-Donec non rutrum lorem. Aenean sagittis metus at pharetra fringilla. Nunc sapien dolor, cursus sed nisi at,
-pretium tristique lectus. Sed pellentesque leo lectus, et convallis ipsum euismod a.
-Integer at leo vitae felis pretium aliquam fringilla quis odio. Sed pharetra enim accumsan feugiat pretium.
-Maecenas at pharetra tortor. Morbi semper eget mi vel finibus. Cras rutrum nulla eros, id feugiat arcu pellentesque ut.
-Sed finibus tortor ac nisi ultrices viverra. Duis feugiat malesuada sapien, at commodo ante porttitor ac.
-Curabitur posuere mauris mi, vel ornare orci scelerisque sit amet. Suspendisse nec fringilla dui.
-
-Document Paragraph
-""""""""""""""""""
-
-Pellentesque nec est in odio ultrices elementum. Vestibulum et hendrerit sapien, quis vulputate turpis.
-Suspendisse potenti. Curabitur tristique sit amet lectus non viverra. Phasellus rutrum dapibus turpis sed imperdiet.
-Mauris maximus viverra ante. Donec eu egestas mauris. Morbi vulputate tincidunt euismod. Integer vel porttitor neque.
-Donec at lacus suscipit, lacinia lectus vel, sagittis lectus.
-
-*********************
-Structural Elements 2
-*********************
-
-Etiam turpis ante, luctus sed velit tristique, finibus volutpat dui. Nam sagittis vel ante nec malesuada.
-Praesent dignissim mi nec ornare elementum. Nunc eu augue vel sem dignissim cursus sed et nulla.
-Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.
-Pellentesque dictum dui sem, non placerat tortor rhoncus in. Sed placerat nulla at rhoncus iaculis.
-
-Document Section
-================
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed condimentum nulla vel neque venenatis,
-nec placerat lorem placerat. Cras purus eros, gravida vitae tincidunt id, vehicula nec nulla.
-Fusce aliquet auctor cursus. Phasellus ex neque, vestibulum non est vitae, viverra fringilla tortor.
-Donec vestibulum convallis justo, a faucibus lorem vulputate vel. Aliquam cursus odio eu felis sodales aliquet.
-Aliquam erat volutpat. Maecenas eget dictum mauris. Suspendisse arcu eros, condimentum eget risus sed,
-luctus efficitur arcu. Cras ut dictum mi. Nulla congue interdum lorem, semper semper enim commodo nec.
-
-Document Subsection
--------------------
-
-.. figure:: static/yi_jing_01_chien.jpg
- :align: right
- :figwidth: 200px
-
- This is a caption for a figure. Text should wrap around the caption.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam efficitur in eros et blandit. Nunc maximus,
-nisl at auctor vestibulum, justo ex sollicitudin ligula, id faucibus urna orci tristique nisl.
-Duis auctor rutrum orci, in ornare lacus condimentum quis. Quisque arcu velit, facilisis quis interdum ac,
-hendrerit auctor mauris. Curabitur urna nibh, porttitor at ante sit amet, vestibulum interdum dolor.
-Duis dictum elit orci, tincidunt imperdiet sem pellentesque et. In vehicula pellentesque varius.
-Phasellus a turpis sollicitudin, bibendum massa et, imperdiet neque. Integer quis sapien in magna rutrum bibendum.
-Integer cursus ex sed magna vehicula finibus. Proin tempus orci quis dolor tempus, nec condimentum odio vestibulum.
-Etiam efficitur sollicitudin libero, tincidunt volutpat ligula interdum sed. Praesent congue sagittis nisl et suscipit.
-Vivamus sagittis risus et egestas commodo.Cras venenatis arcu in pharetra interdum.
-Donec quis metus porttitor tellus cursus lobortis. Quisque et orci magna. Fusce rhoncus mi mi,
-at vehicula massa rhoncus quis. Mauris augue leo, pretium eget molestie vitae, efficitur nec nulla.
-In hac habitasse platea dictumst. Sed sit amet imperdiet purus.
-
-
-.. meta::
- :description lang=en:
- Examples of document structure features in pydata-sphinx-theme.
diff --git a/docs/demo/subpages/index.rst b/docs/demo/subpages/index.rst
index 0652e10ab..068452e5a 100644
--- a/docs/demo/subpages/index.rst
+++ b/docs/demo/subpages/index.rst
@@ -1,5 +1,5 @@
-Section with sub-pages
-======================
+Section to show off pages with many sub-pages
+=============================================
To create an additional level of nesting in the sidebar, construct a
nested ``toctree``:
diff --git a/docs/demo/subpages2/index.rst b/docs/demo/subpages2/index.rst
deleted file mode 100644
index 2e9d7938a..000000000
--- a/docs/demo/subpages2/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-A second section with sub-pages
-===============================
-
-To create an additional level of nesting in the sidebar, construct a
-nested ``toctree``:
-
-.. toctree::
-
- subpage1
- subpage2
diff --git a/docs/demo/subpages2/subpage1.rst b/docs/demo/subpages2/subpage1.rst
deleted file mode 100644
index b521913d6..000000000
--- a/docs/demo/subpages2/subpage1.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Sub-page 1
-==========
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,
-finibus dictum velit. Ut eu efficitur arcu, id aliquam erat. In sit amet diam gravida, imperdiet tellus eu,
-gravida nisl. Praesent aliquet odio eget libero elementum, quis rhoncus tellus tincidunt.
-Suspendisse quis volutpat ipsum. Sed lobortis scelerisque tristique. Aenean condimentum risus tellus,
-quis accumsan ipsum laoreet ut. Integer porttitor maximus suscipit. Mauris in posuere sapien.
-Aliquam accumsan feugiat ligula, nec fringilla libero commodo sed. Proin et erat pharetra.
diff --git a/docs/demo/subpages2/subpage2.rst b/docs/demo/subpages2/subpage2.rst
deleted file mode 100644
index f6c585a38..000000000
--- a/docs/demo/subpages2/subpage2.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Sub-page 2
-==========
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec,
-finibus dictum velit. Ut eu efficitur arcu, id aliquam erat. In sit amet diam gravida, imperdiet tellus eu,
-gravida nisl. Praesent aliquet odio eget libero elementum, quis rhoncus tellus tincidunt.
-Suspendisse quis volutpat ipsum. Sed lobortis scelerisque tristique. Aenean condimentum risus tellus,
-quis accumsan ipsum laoreet ut. Integer porttitor maximus suscipit. Mauris in posuere sapien.
-Aliquam accumsan feugiat ligula, nec fringilla libero commodo sed. Proin et erat pharetra.
diff --git a/docs/demo/theme-elements.md b/docs/demo/theme-elements.md
new file mode 100644
index 000000000..8e1703435
--- /dev/null
+++ b/docs/demo/theme-elements.md
@@ -0,0 +1,73 @@
+# Theme-specific elements
+
+There are a few elements that are unique or particularly important to this theme.
+This page is a reference for how these look.
+
+## Embedding in admonitions
+
+````{note}
+Here's a note with:
+
+- A nested list
+- List item two
+
+As well as:
+
+```{warning}
+A nested warning block to test nested admonitions.
+```
+````
+
+## Version changes
+
+You can write in your documentation when something has been changed,
+added or deprecated from one version to another.
+
+```{versionadded} 0.1.1
+Something is new, use it from now.
+```
+
+```{versionchanged} 0.1.1
+Something is modified, check your version number.
+```
+
+```{deprecated} 0.1.1
+Something is deprecated, use something else instead.
+```
+
+## HTML elements
+
+There are some libraries in the PyData ecosystem that use HTML and require their own styling.
+This section shows a few examples.
+
+### Plotly
+
+The HTML below shouldn't display, but it uses RequireJS to make sure that all
+works as expected. If the widgets don't show up, RequireJS may be broken.
+
+```{jupyter-execute}
+import plotly.io as pio
+import plotly.express as px
+import plotly.offline as py
+
+pio.renderers.default = "notebook"
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", size="sepal_length")
+fig
+```
+
+### Xarray
+
+Here we demonstrate `xarray` to ensure that it shows up properly.
+
+```{jupyter-execute}
+import xarray as xr
+import numpy as np
+data = xr.DataArray(
+ np.random.randn(2, 3),
+ dims=("x", "y"),
+ coords={"x": [10, 20]}, attrs={"foo": "bar"}
+ )
+data
+```
diff --git a/docs/scripts/a11y-roadmap.txt b/docs/scripts/a11y-roadmap.txt
index 8c3ed0f99..a0071ed09 100644
--- a/docs/scripts/a11y-roadmap.txt
+++ b/docs/scripts/a11y-roadmap.txt
@@ -7,3 +7,6 @@ WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail
WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2
WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.EmptyNoId
WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.NoContent
+
+# This is an expected error on the kitchen-sink pages which have a non-existent reference
+WCAG2AA.Principle2.Guideline2_4.2_4_1.G1,G123,G124.NoSuchID