Infra: Update documentation and ``build.py`` (#3420)

- Always fail on warnings, remove the related flag
- Nitpicky is now enabled in ``conf.py``, remove the related flag
- Use direct links to PEPs rather than Sphinx-only ``:doc:`` roles
- Remove references to ``AUTHOR_OVERRIDES.csv``, which is no longer used
- Fix indentation for an enumerated list

build.py

@@ -5,6 +5,7 @@
 """Build script for Sphinx documentation"""
 
 import argparse
+import os
 from pathlib import Path
 
 from sphinx.application import Sphinx
@@ -27,15 +28,6 @@ def create_parser():
                           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",
-                        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.")
     parser.add_argument(
         "-o",
         "--output-dir",
@@ -61,33 +53,23 @@ def create_index_file(html_root: Path, builder: str) -> None:
 if __name__ == "__main__":
     args = create_parser()
 
-    root_directory = Path(".").absolute()
+    root_directory = Path(__file__).resolve().parent
     source_directory = root_directory
     build_directory = root_directory / args.output_dir
-    doctree_directory = build_directory / ".doctrees"
 
     # builder configuration
-    if args.builder is not None:
+    sphinx_builder = args.builder or "html"
-        sphinx_builder = args.builder
-    else:
-        # default builder
-        sphinx_builder = "html"
-
-    # other configuration
-    config_overrides = {}
-    if args.nitpicky:
-        config_overrides["nitpicky"] = True
 
     app = Sphinx(
         source_directory,
         confdir=source_directory,
-        outdir=build_directory,
+        outdir=build_directory / sphinx_builder,
-        doctreedir=doctree_directory,
+        doctreedir=build_directory / "doctrees",
         buildername=sphinx_builder,
-        confoverrides=config_overrides,
+        warningiserror=True,
-        warningiserror=args.fail_on_warning,
+        parallel=os.cpu_count() or 1,
-        parallel=args.jobs,
         tags=["internal_builder"],
+        keep_going=True,
     )
     app.build()
 

docs/build.rst

@@ -1,5 +1,4 @@
-..
+:author: Adam Turner
-   Author: Adam Turner
 
 
 Building PEPs Locally
@@ -10,8 +9,8 @@ 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 
+`PEPs repository <https://github.com/python/peps>`__,
-**Python 3.9 or later** installed.
+with **Python 3.9 or later** installed.
 
 
 Render PEPs locally
@@ -51,11 +50,6 @@ Render PEPs locally
 
       (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.
 
@@ -91,26 +85,6 @@ Check the validity of links within PEP sources (runs the `Sphinx linkchecker
    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:: shell
-
-    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:: shell
-
-    python build.py --fail-on-warning
-    make fail-warning
-
-
 ``build.py`` usage
 ------------------
 

docs/rendering_system.rst

@@ -1,6 +1,6 @@
-..
+:author: Adam Turner
-   Author: Adam Turner
 
+..
    We can't use :pep:`N` references in this document, as they use links relative
    to the current file, which doesn't work in a subdirectory like this one.
 
@@ -9,7 +9,7 @@ An Overview of the PEP Rendering System
 =======================================
 
 This document provides an overview of the PEP rendering system, as a companion
-to :doc:`PEP 676 <../pep-0676>`.
+to `PEP 676 <https://peps.python.org/pep-0676/>`__.
 
 
 1. Configuration
@@ -18,7 +18,7 @@ to :doc:`PEP 676 <../pep-0676>`.
 Configuration is stored in three files:
 
 - ``conf.py`` contains the majority of the Sphinx configuration
-- ``contents.rst`` creates the Sphinx-mandated table of contents directive
+- ``contents.rst`` contains the compulsory table of contents directive
 - ``pep_sphinx_extensions/pep_theme/theme.conf`` sets the Pygments themes
 
 The configuration:
@@ -110,7 +110,8 @@ This overrides the built-in ``:pep:`` role to return the correct URL.
 3.4.2 ``PEPHeaders`` transform
 ******************************
 
-PEPs start with a set of :rfc:`2822` headers, per :doc:`PEP 1 <../pep-0001>`.
+PEPs start with a set of :rfc:`2822` headers,
+per `PEP 1 <https://peps.python.org/pep-0001/>`__.
 This transform validates that the required headers are present and of the
 correct data type, and removes headers not for display.
 It must run before the ``PEPTitle`` transform.
@@ -122,7 +123,7 @@ It must run before the ``PEPTitle`` transform.
 We generate the title node from the parsed title in the PEP headers, and make
 all nodes in the document children of the new title node.
 This transform must also handle parsing reStructuredText markup within PEP
-titles, such as :doc:`PEP 604 <../pep-0604>`.
+titles, such as `PEP 604 <https://peps.python.org/pep-0604/>`__.
 
 
 3.4.4 ``PEPContents`` transform
@@ -220,9 +221,6 @@ three steps:
 2. Output the category and numerical indices
 3. Output the author index
 
-The ``AUTHOR_OVERRIDES.csv`` file can be used to override an author's name in
-the PEP 0 output.
-
 We then add the newly created PEP 0 file to two Sphinx variables so that it will
 be processed as a normal source document.