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