From 497250afe0734181ae732218b8c24396bf55bd97 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 3 Sep 2023 22:08:42 +0100 Subject: [PATCH] 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 | 34 ++++++++-------------------------- docs/build.rst | 38 ++++++-------------------------------- docs/rendering_system.rst | 22 ++++++++++------------ 3 files changed, 24 insertions(+), 70 deletions(-) diff --git a/build.py b/build.py index 8f0ead024..ebc3cf4aa 100755 --- a/build.py +++ b/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 - else: - # default builder - sphinx_builder = "html" - - # other configuration - config_overrides = {} - if args.nitpicky: - config_overrides["nitpicky"] = True + sphinx_builder = args.builder or "html" app = Sphinx( source_directory, confdir=source_directory, - outdir=build_directory, - doctreedir=doctree_directory, + outdir=build_directory / sphinx_builder, + doctreedir=build_directory / "doctrees", buildername=sphinx_builder, - confoverrides=config_overrides, - warningiserror=args.fail_on_warning, - parallel=args.jobs, + warningiserror=True, + parallel=os.cpu_count() or 1, tags=["internal_builder"], + keep_going=True, ) app.build() diff --git a/docs/build.rst b/docs/build.rst index ae4ac1848..d59b2f804 100644 --- a/docs/build.rst +++ b/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 `__, with -**Python 3.9 or later** installed. +`PEPs repository `__, +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. @@ -87,28 +81,8 @@ Check the validity of links within PEP sources (runs the `Sphinx linkchecker .. code-block:: shell - python build.py --check-links - make check-links - - -Stricter rendering -'''''''''''''''''' - -Run in `nit-picky `__ -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 + python build.py --check-links + make check-links ``build.py`` usage @@ -118,4 +92,4 @@ For details on the command-line options to the ``build.py`` script, run: .. code-block:: shell - python build.py --help + python build.py --help diff --git a/docs/rendering_system.rst b/docs/rendering_system.rst index 9a298e0e8..83c077e7a 100644 --- a/docs/rendering_system.rst +++ b/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 `__. 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 `__. 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 `__. 3.4.4 ``PEPContents`` transform @@ -216,12 +217,9 @@ parse and validate that metadata. After collecting and validating all the PEP data, the index itself is created in three steps: - 1. Output the header text - 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. +1. Output the header text +2. Output the category and numerical indices +3. Output the author index We then add the newly created PEP 0 file to two Sphinx variables so that it will be processed as a normal source document.