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
This commit is contained in:
Adam Turner
GitHub
parent
2d4c98dca7
commit
497250afe0
34
build.py
34
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()
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
**Python 3.9 or later** installed.
|
||||
`PEPs repository <https://github.com/python/peps>`__,
|
||||
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 <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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue