DOC: Update kitchen sink (#610)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/tests.yml

@@ -93,8 +93,9 @@ jobs:
       run: |
         from pathlib import Path
         text = Path("./warnings.txt").read_text().strip()
+        expected_warning_snippets = ["kitchen-sink", "urllib/parse.py"]
         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]
+        unexpected = [ii for ii in text.split("\n") if not any(snippet in ii for snippet in expected_warning_snippets)]
         assert len(unexpected) == 0
 
     - name: Audit with Lighthouse

docs/conf.py

@@ -1,7 +1,5 @@
 # -- Project information -----------------------------------------------------
 import os
-from pathlib import Path
-from urllib import request
 
 project = "Sphinx Book Theme"
 copyright = "2020"
@@ -31,6 +29,8 @@
     "sphinx_togglebutton",
     "sphinxcontrib.bibtex",
     "sphinxext.opengraph",
+    # For the kitchen sink
+    "sphinx.ext.todo",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -153,27 +153,6 @@
     "https://doi.org",  # These don't resolve properly and cause SSL issues
 ]
 
-# -- Download kitchen sink reference docs -------------------------------------
-# These are the kitchen sink files used by the Sphinx Themes gallery at
-# https://github.com/sphinx-themes/sphinx-themes.org
-# To re-download, delete the `references/kitchen-sink` folder and build the docs
-kitchen_sink_files = [
-    "api.rst",
-    "index.rst",
-    "lists-and-tables.rst",
-    "paragraph-markup.rst",
-]
-for ifile in kitchen_sink_files:
-    path_file = Path(f"reference/kitchen-sink/{ifile}")
-    path_file.parent.mkdir(exist_ok=True)
-    if not path_file.exists():
-        print(f"Downloading kitchen sink file {ifile}")
-        resp = request.urlopen(
-            f"https://github.com/sphinx-themes/sphinx-themes.org/raw/master/sample-docs/kitchen-sink/{ifile}"  # noqa: E501
-        )
-        header = ".. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT\n"
-        path_file.write_text(header + resp.read().decode())
-
 
 def setup(app):
     # -- To demonstrate ReadTheDocs switcher -------------------------------------

docs/reference/extensions.md

@@ -20,9 +20,6 @@ And here's a bibliography:
 ```{bibliography}
 ```
 
-:::{seealso}
-See the [paragraph markup page](kitchen-sink/paragraph-markup.rst) for more references styling.
-:::
 
 ## `ABlog` - Blog post list
 

docs/reference/kitchen-sink/admonitions.rst

@@ -0,0 +1,123 @@
+..
+   Copyright (c) 2021 Pradyun Gedam
+   Licensed under Creative Commons Attribution-ShareAlike 4.0 International License
+   SPDX-License-Identifier: CC-BY-SA-4.0
+
+===========
+Admonitions
+===========
+
+Sphinx provides several different types of admonitions.
+
+``topic``
+=========
+
+.. topic:: This is a topic.
+
+   This is what admonitions are a special case of, according to the docutils
+   documentation.
+
+``admonition``
+==============
+
+.. admonition:: The one with the custom titles
+
+   It's got a certain charm to it.
+
+``attention``
+=============
+
+.. attention::
+
+   Climate change is real.
+
+``caution``
+===========
+
+.. caution::
+
+   Cliff ahead: Don't drive off it.
+
+``danger``
+==========
+
+.. danger::
+
+   Mad scientist at work!
+
+``error``
+=========
+
+.. error::
+
+   Does not compute.
+
+``hint``
+========
+
+.. hint::
+
+   Insulators insulate, until they are subject to ______ voltage.
+
+``important``
+=============
+
+.. important::
+
+   Tech is not neutral, nor is it apolitical.
+
+``note``
+========
+
+.. note::
+
+   This is a note.
+
+``seealso``
+===========
+
+.. seealso::
+
+   Other relevant information.
+
+``tip``
+=======
+
+.. tip::
+
+   25% if the service is good.
+
+``todo``
+========
+
+.. todo::
+
+   This needs the ``sphinx.ext.todo`` extension.
+
+``warning``
+===========
+
+.. warning::
+
+   Reader discretion is strongly advised.
+
+``versionadded``
+================
+
+.. versionadded:: v0.1.1
+
+   Here's a version added message.
+
+``versionchanged``
+==================
+
+.. versionchanged:: v0.1.1
+
+   Here's a version changed message.
+
+``deprecated``
+==============
+
+.. deprecated:: v0.1.1
+
+   Here's a deprecation message.

docs/reference/kitchen-sink/api.rst

@@ -1,10 +1,29 @@
-.. DOWNLOADED FROM sphinx-themes.org, DO NOT MANUALLY EDIT
+..
+   Copyright (c) 2021 Pradyun Gedam
+   Licensed under Creative Commons Attribution-ShareAlike 4.0 International License
+   SPDX-License-Identifier: CC-BY-SA-4.0
+
 *****************
 API documentation
 *****************
 
-``asyncio``
-===========
+Using Sphinx's ``sphinx.ext.autodoc`` plugin, it is possible to auto-generate documentation of a Python module.
+
+.. tip::
+    Avoid having in-function-signature type annotations with autodoc,
+    by setting the following options:
+
+    .. code-block:: python
+
+        # -- Options for autodoc ----------------------------------------------------
+        # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+        # Automatically extract typehints when specified and place them in
+        # descriptions of the relevant function/method.
+        autodoc_typehints = "description"
+
+        # Don't show class signature with the class' name.
+        autodoc_class_signature = "separated"
 
-.. automodule:: asyncio
-    :members: run, gather, AbstractEventLoop
+.. automodule:: urllib.parse
+    :members: