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

…te (#2239)

Co-authored-by: C.A.M. Gerlach <cam.gerlach@gerlach.cam>

Makefile

@@ -65,15 +65,11 @@ pep_rss:
 	$(PYTHON) generate_rss.py
 
 pages: pep_rss
-	$(SPHINX_BUILD) --index-file
+	$(SPHINX_BUILD) --build-dirs
 
 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

@@ -1,3 +1,7 @@
+#!/usr/bin/env python3
+# This file is placed in the public domain or under the
+# CC0-1.0-Universal license, whichever is more permissive.
+
 """Build script for Sphinx documentation"""
 
 import argparse
@@ -9,17 +13,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")
+    builders = parser.add_mutually_exclusive_group()
+    builders.add_argument("-l", "--check-links", action="store_const",
+                          dest="builder", const="linkcheck",
+                          help='Check validity of links within PEP sources. '
+                               'Cannot be used with "-f" or "-d".')
+    builders.add_argument("-f", "--build-files", action="store_const",
+                          dest="builder", const="html",
+                          help='Render PEPs to "pep-NNNN.html" files (default). '
+                               'Cannot be used with "-d" or "-l".')
+    builders.add_argument("-d", "--build-dirs", action="store_const",
+                          dest="builder", const="dirhtml",
+                          help='Render PEPs to "index.html" files within "pep-NNNN" 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)
-
-    # extra build steps
-    parser.add_argument("-i", "--index-file", action="store_true")  # for PEP 0
+    parser.add_argument("-w", "--fail-on-warning", action="store_true",
+                        help="Fail the Sphinx build on any warning.")
+    parser.add_argument("-n", "--nitpicky", action="store_true",
+                        help="Run 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.")
 
     return parser.parse_args()
 
@@ -45,15 +61,11 @@ def create_index_file(html_root: Path, builder: str) -> None:
     doctree_directory = build_directory / ".doctrees"
 
     # builder configuration
-    if args.build_files:
-        sphinx_builder = "html"
-    elif args.build_dirs:
-        sphinx_builder = "dirhtml"
-    elif args.check_links:
-        sphinx_builder = "linkcheck"
+    if args.builder is not None:
+        sphinx_builder = args.builder
     else:
         # default builder
-        sphinx_builder = "dirhtml"
+        sphinx_builder = "html"
 
     # other configuration
     config_overrides = {}
@@ -71,6 +83,5 @@ def create_index_file(html_root: Path, builder: str) -> None:
         parallel=args.jobs,
     )
     app.build()
-
-    if args.index_file:
-        create_index_file(build_directory, sphinx_builder)
+
+    create_index_file(build_directory, sphinx_builder)

conf.py

@@ -1,3 +1,6 @@
+# This file is placed in the public domain or under the
+# CC0-1.0-Universal license, whichever is more permissive.
+
 """Configuration for building PEPs using Sphinx."""
 
 from pathlib import Path
@@ -43,7 +46,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

@@ -1,9 +1,11 @@
+.. This file is placed in the public domain or under the
+   CC0-1.0-Universal license, whichever is more permissive.
 
 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,106 @@
+..
+   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.
+
+   The rest of these instructions assume an active virtual environment named
+   ``venv``.
+   The Python Packaging User Guide contains
+   `instructions on creating a virtual environment <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`__
+   for reference.
+
+   .. code-block:: console
+
+      (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
+
+   .. 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
+
+
+``build.py`` usage
+------------------
+
+For details on the command-line options to the ``build.py`` script, run:
+
+.. code-block:: console
+
+    (venv) $ python build.py --help