Permalink
Cannot retrieve contributors at this time
Name already in use
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
peps/build.py /
Go to fileThis commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/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 | |
| from pathlib import Path | |
| from sphinx.application import Sphinx | |
| def create_parser(): | |
| parser = argparse.ArgumentParser(description="Build PEP documents") | |
| # alternative builders: | |
| 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", | |
| 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", | |
| default="build", # synchronise with render.yaml -> deploy step | |
| help="Output directory, relative to root. Default 'build'.", | |
| ) | |
| return parser.parse_args() | |
| def create_index_file(html_root: Path, builder: str) -> None: | |
| """Copies PEP 0 to the root index.html so that /peps/ works.""" | |
| pep_zero_file = "pep-0000.html" if builder == "html" else "pep-0000/index.html" | |
| try: | |
| pep_zero_text = html_root.joinpath(pep_zero_file).read_text(encoding="utf-8") | |
| except FileNotFoundError: | |
| return None | |
| if builder == "dirhtml": | |
| pep_zero_text = pep_zero_text.replace('="../', '="') # remove relative directory links | |
| html_root.joinpath("index.html").write_text(pep_zero_text, encoding="utf-8") | |
| if __name__ == "__main__": | |
| args = create_parser() | |
| root_directory = Path(".").absolute() | |
| 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 | |
| app = Sphinx( | |
| source_directory, | |
| confdir=source_directory, | |
| outdir=build_directory, | |
| doctreedir=doctree_directory, | |
| buildername=sphinx_builder, | |
| confoverrides=config_overrides, | |
| warningiserror=args.fail_on_warning, | |
| parallel=args.jobs, | |
| tags=["internal_builder"], | |
| ) | |
| app.build() | |
| create_index_file(build_directory, sphinx_builder) |