DOCS: Refactor demo docs (#544)

.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 }}

docs/conf.py

@@ -127,6 +127,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
 }
 
 

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).
+:::

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.

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 <https://jupyterbook.org/>
 
 .. 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:

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

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

docs/demo/lists_tables.rst → 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 <http://www.yahoo.com>`_
   - `yahoo <http://www.yahoo.com>`_
   - ``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.