PEP 676: 'dark mode', documentation, spec update, implementation update

.github/workflows/deploy-gh-pages.yaml

@@ -2,7 +2,6 @@ name: Deploy to GitHub Pages
 
 on:
   push:
-    branches: [main]
 
 jobs:
   deploy-to-pages:

Makefile

@@ -65,15 +65,11 @@ pep_rss:
 	$(PYTHON) generate_rss.py
 
 pages: pep_rss
-	$(SPHINX_BUILD) --index-file
+	$(SPHINX_BUILD) --build-dirs --index-file
 
 sphinx:
 	$(SPHINX_BUILD)
 
-# for building Sphinx without a web-server
-sphinx-local:
-	$(SPHINX_BUILD) --build-files
-
 fail-warning:
 	$(SPHINX_BUILD) --fail-on-warning
 

build.py

@@ -9,17 +9,29 @@
 def create_parser():
     parser = argparse.ArgumentParser(description="Build PEP documents")
     # alternative builders:
-    parser.add_argument("-l", "--check-links", action="store_true")
-    parser.add_argument("-f", "--build-files", action="store_true")
-    parser.add_argument("-d", "--build-dirs", action="store_true")
+    parser.add_argument("-l", "--check-links", action="store_true",
+                        help='Checks validity of links within PEP sources. '
+                             'Cannot be used with "-f" or "-d".')
+    parser.add_argument("-f", "--build-files", action="store_true",
+                        help='Renders PEPs to "pep-XXXX.html" files (Default). '
+                             'Cannot be used with "-d" or "-l".')
+    parser.add_argument("-d", "--build-dirs", action="store_true",
+                        help='Renders PEPs to "index.html" files within "pep-XXXX" directories. '
+                             'Cannot be used with "-f" or "-l".')
 
     # flags / options
-    parser.add_argument("-w", "--fail-on-warning", action="store_true")
-    parser.add_argument("-n", "--nitpicky", action="store_true")
-    parser.add_argument("-j", "--jobs", type=int, default=1)
+    parser.add_argument("-w", "--fail-on-warning", action="store_true",
+                        help="Fails Sphinx on warnings.")
+    parser.add_argument("-n", "--nitpicky", action="store_true",
+                        help="Runs Sphinx in 'nitpicky' mode, "
+                             "warning on every missing reference target.")
+    parser.add_argument("-j", "--jobs", type=int, default=1,
+                        help="How many parallel jobs to run (if supported). "
+                             "Integer, default 1.")
 
     # extra build steps
-    parser.add_argument("-i", "--index-file", action="store_true")  # for PEP 0
+    parser.add_argument("-i", "--index-file", action="store_true",  # for PEP 0
+                        help="Copies PEP 0 to a base index file.")
 
     return parser.parse_args()
 
@@ -53,7 +65,7 @@ def create_index_file(html_root: Path, builder: str) -> None:
         sphinx_builder = "linkcheck"
     else:
         # default builder
-        sphinx_builder = "dirhtml"
+        sphinx_builder = "html"
 
     # other configuration
     config_overrides = {}

conf.py

@@ -43,7 +43,6 @@
 
 # HTML output settings
 html_math_renderer = "maths_to_html"  # Maths rendering
-html_title = "peps.python.org"  # Set <title/>
 
 # Theme settings
 html_theme_path = ["pep_sphinx_extensions"]

contents.rst

@@ -3,7 +3,7 @@ Python Enhancement Proposals (PEPs)
 ***********************************
 
 
-This is an internal Sphinx page, please go to the :doc:`PEP Index<pep-0000>`.
+This is an internal Sphinx page, please go to the :doc:`PEP Index <pep-0000>`.
 
 
 .. toctree::

docs/build.rst

@@ -0,0 +1,102 @@
+..
+   Author: Adam Turner
+
+
+Building PEPs Locally
+=====================
+
+Whilst editing a PEP, it is useful to review the rendered output locally.
+This can also be used to check that the PEP is valid reStructuredText before
+submission to the PEP editors.
+
+The rest of this document assumes you are working from a local clone of the
+`PEPs repository <https://github.com/python/peps>`__, with Python 3.9 or later
+installed.
+
+
+Render PEPs locally
+-------------------
+
+1. Create a virtual environment and install requirements
+
+   .. code-block:: console
+
+      $ python -m venv venv
+      $ . venv/bin/activate
+      (venv) $ python -m pip install --upgrade pip
+      (venv) $ python -m pip install -r requirements.txt
+
+2. **(Optional)** Delete prior build files.
+   Generally only needed when making changes to the rendering system itself.
+
+   .. code-block:: console
+
+      $ rm -rf build
+
+3. Run the build script:
+
+   .. code-block:: console
+
+      (venv) $ make sphinx
+
+   If you don't have access to ``make``, run:
+
+   .. code-block:: ps1con
+
+      (venv) PS> python build.py -j 8
+
+   .. note::
+
+      There may be a series of warnings about unreferenced citations or labels.
+      Whilst these are valid warnings, they do not impact the build process.
+
+4. Navigate to the ``build`` directory of your PEPs repo to find the HTML pages.
+   PEP 0 provides a formatted index, and may be a useful reference.
+
+
+``build.py`` tools
+------------------
+
+Several additional tools can be run through ``build.py``, or the Makefile.
+
+
+Check links
+'''''''''''
+
+Check the validity of links within PEP sources (runs the `Sphinx linkchecker
+<https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder>`__).
+
+.. code-block:: console
+
+    (venv) $ python build.py --check-links
+    (venv) $ make check-links
+
+
+Stricter rendering
+''''''''''''''''''
+
+Run in `nit-picky <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky>`__
+mode.
+This generates warnings for all missing references.
+
+.. code-block:: console
+
+    (venv) $ python build.py --nitpicky
+
+Fail the build on any warning.
+As of January 2022, there are around 250 warnings when building the PEPs.
+
+.. code-block:: console
+
+    (venv) $ python build.py --fail-on-warning
+    (venv) $ make fail-warning
+
+
+All arguments to ``build.py``
+-----------------------------
+
+For details on options to ``build.py``, run:
+
+.. code-block:: console
+
+    (venv) $ python build.py --help