From 0bb832e1f9591508b217f482bb47e171dda4b741 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Apr 2021 05:36:59 +0100 Subject: [PATCH 01/10] Update .gitignore --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index e6e16dd974f..b9c89215748 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,5 @@ __pycache__ .vscode *.swp /build +/package +/venv From 4e7f7e0fc8070580118db0581f436ce6097dd6e7 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Apr 2021 05:37:48 +0100 Subject: [PATCH 02/10] Add base sphinx build script --- build.py | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 build.py diff --git a/build.py b/build.py new file mode 100644 index 00000000000..be051938974 --- /dev/null +++ b/build.py @@ -0,0 +1,46 @@ +"""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") + # builders: + parser.add_argument("-b", "--builder", default="html", choices=("html", "dirhtml", "linkcheck")) + + # checks + parser.add_argument("-f", "--fail-on-warning", action="store_true") + parser.add_argument("-n", "--nitpicky", action="store_true") + + # extra build steps + parser.add_argument("-i", "--index-file", action="store_true") # for PEP 0 + + return parser.parse_args() + + +if __name__ == "__main__": + args = create_parser() + + root_directory = Path(".").absolute() + source_directory = root_directory + build_directory = root_directory / "build" + doctree_directory = build_directory / ".doctrees" + + config_overrides = {} + if args.nitpicky: + config_overrides["nitpicky"] = True + + app = Sphinx( + source_directory, + confdir=source_directory, + outdir=build_directory, + doctreedir=doctree_directory, + buildername=args.builder, + confoverrides=config_overrides, + warningiserror=args.fail_on_warning, + ) + app.builder.copysource = False # Prevent unneeded source copying - we link direct to GitHub + app.build() From 332ffb93f063b25c86cfa6d87444423831187588 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Apr 2021 05:38:02 +0100 Subject: [PATCH 03/10] Add requirements file --- requirements.txt | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 requirements.txt diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000000..99202ceca35 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +# Requirements for building PEPs with Sphinx +sphinx >= 3.5 +docutils >= 0.16 From 855cf8bd9f59b303425edfbf0d06da7f63a458c4 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Apr 2021 05:38:36 +0100 Subject: [PATCH 04/10] Update Makefile with sphinx targets --- Makefile | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 889134e6d48..284611a6a34 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,5 @@ -# Rules to only make the required HTML versions, not all of them, -# without the user having to keep track of which. -# -# Not really important, but convenient. +# Builds PEP files to HTML using sphinx +# Also contains testing targets PEP2HTML=pep2html.py @@ -34,7 +32,6 @@ install: clean: -rm pep-0000.rst - -rm pep-0000.txt -rm *.html -rm -rf build @@ -43,7 +40,7 @@ update: venv: $(PYTHON) -m venv $(VENV_DIR) - ./$(VENV_DIR)/bin/python -m pip install -U docutils + ./$(VENV_DIR)/bin/python -m pip install -r requirements.txt package: all rss mkdir -p build/peps @@ -57,3 +54,24 @@ package: all rss lint: pre-commit --version > /dev/null || python3 -m pip install pre-commit pre-commit run --all-files + +pages: rss + $(PYTHON) build.py --index-file + +sphinx: + $(PYTHON) build.py + +fail_on_warning: + $(PYTHON) build.py -f + +check_links: + $(PYTHON) build.py -c + +sphinx_package: all rss + mkdir -p package/peps + $(PYTHON) package.py + cp pep-*.txt build/peps/ + cp pep-*.rst build/peps/ + cp *.png build/peps/ + cp *.rss package/peps + tar -C package -czf package/peps.tar.gz peps From 0f2033e932dadcf8ac0f589dc0e42d3b1e7a9dcd Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Apr 2021 05:45:01 +0100 Subject: [PATCH 05/10] Add GH actions deploy script --- .github/workflows/deploy-gh-pages.yaml | 44 ++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 .github/workflows/deploy-gh-pages.yaml diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml new file mode 100644 index 00000000000..6bbadab5d4e --- /dev/null +++ b/.github/workflows/deploy-gh-pages.yaml @@ -0,0 +1,44 @@ +name: Deploy to GitHub Pages + +on: [push] + +jobs: + deploy-to-pages: + runs-on: ubuntu-latest + + steps: + - name: 🛎️ Checkout + uses: actions/checkout@v2 + + - name: 🐍 Set up Python 3.9 + uses: actions/setup-python@v2 + with: + python-version: 3.9 + + - name: 🧳 Cache pip + uses: actions/cache@v2 + with: + # This path is specific to Ubuntu + path: ~/.cache/pip + # Look to see if there is a cache hit for the corresponding requirements file + key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }} + restore-keys: | + ${{ runner.os }}-pip- + ${{ runner.os }}- + + # Install dependencies and build PEPs using sphinx + - name: 👷‍ Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + make pages + + # Install dependencies and build PEPs using sphinx + - name: 🔧 Build PEPs + run: make pages + + - name: 🚀 Deploy to GitHub pages + uses: JamesIves/github-pages-deploy-action@4.1.1 + with: + BRANCH: gh-pages # The branch the action should deploy to. + FOLDER: build # The folder the action should deploy. From d2c92d537f4ae296464369c85c3d18df4474d85d Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Apr 2021 05:55:33 +0100 Subject: [PATCH 06/10] Add conf.py and contents.rst for Sphinx --- conf.py | 37 +++++++++++++++++++++++++++++++++++++ contents.rst | 16 ++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 conf.py create mode 100644 contents.rst diff --git a/conf.py b/conf.py new file mode 100644 index 00000000000..34835c38a3b --- /dev/null +++ b/conf.py @@ -0,0 +1,37 @@ +"""Configuration for building PEPs using Sphinx.""" + +# -- Project information ----------------------------------------------------- + +project = "PEPs" +master_doc = "contents" + +# -- General configuration --------------------------------------------------- + +# The file extensions of source files. Sphinx uses these suffixes as sources. +source_suffix = { + ".rst": "restructuredtext", + ".txt": "restructuredtext", +} + +# List of patterns (relative to source dir) to ignore when looking for source files. +exclude_patterns = [ + # Windows: + "Thumbs.db", + ".DS_Store", + # Python: + "venv", + "requirements.txt", + # Sphinx: + "build", + "output.txt", # Link-check output + # PEPs: + "README.rst", + "CONTRIBUTING.rst", +] + +# -- Options for HTML output ------------------------------------------------- + +# HTML output settings +html_show_copyright = False # Turn off miscellany +html_show_sphinx = False +html_title = "peps.python.org" # Set diff --git a/contents.rst b/contents.rst new file mode 100644 index 00000000000..658655e4044 --- /dev/null +++ b/contents.rst @@ -0,0 +1,16 @@ + +Python Enhancement Proposals (PEPs) +*********************************** + + +This is an internal Sphinx page, please go to the :doc:`PEP Index<pep-0000>`. + + +.. toctree:: + :maxdepth: 3 + :titlesonly: + :hidden: + :glob: + :caption: PEP Table of Contents (needed for Sphinx): + + pep-* \ No newline at end of file From b162d530208e71af5cf33f27165203ba35338ec4 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Apr 2021 17:30:18 +0100 Subject: [PATCH 07/10] Add parallel deploy --- .github/workflows/deploy-gh-pages.yaml | 5 +---- Makefile | 15 ++++++++++----- build.py | 4 +++- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml index 6bbadab5d4e..fec3f7156ae 100644 --- a/.github/workflows/deploy-gh-pages.yaml +++ b/.github/workflows/deploy-gh-pages.yaml @@ -26,16 +26,13 @@ jobs: ${{ runner.os }}-pip- ${{ runner.os }}- - # Install dependencies and build PEPs using sphinx - name: 👷‍ Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt - make pages - # Install dependencies and build PEPs using sphinx - name: 🔧 Build PEPs - run: make pages + run: make pages -j$(nproc) - name: 🚀 Deploy to GitHub pages uses: JamesIves/github-pages-deploy-action@4.1.1 diff --git a/Makefile b/Makefile index 284611a6a34..ddd70e96981 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# Builds PEP files to HTML using sphinx +# Builds PEP files to HTML using docutils or sphinx # Also contains testing targets PEP2HTML=pep2html.py @@ -55,17 +55,22 @@ lint: pre-commit --version > /dev/null || python3 -m pip install pre-commit pre-commit run --all-files +# New Sphinx targets: + +SPHINX_JOBS=8 +SPHINX_BUILD=$(PYTHON) build.py -j $(SPHINX_JOBS) + pages: rss - $(PYTHON) build.py --index-file + $(SPHINX_BUILD) --index-file sphinx: - $(PYTHON) build.py + $(SPHINX_BUILD) fail_on_warning: - $(PYTHON) build.py -f + $(SPHINX_BUILD) --fail-on-warning check_links: - $(PYTHON) build.py -c + $(SPHINX_BUILD) --builder linkcheck sphinx_package: all rss mkdir -p package/peps diff --git a/build.py b/build.py index be051938974..e5c1f418143 100644 --- a/build.py +++ b/build.py @@ -11,9 +11,10 @@ def create_parser(): # builders: parser.add_argument("-b", "--builder", default="html", choices=("html", "dirhtml", "linkcheck")) - # checks + # flags / options parser.add_argument("-f", "--fail-on-warning", action="store_true") parser.add_argument("-n", "--nitpicky", action="store_true") + parser.add_argument("-j", "--jobs", type=int) # extra build steps parser.add_argument("-i", "--index-file", action="store_true") # for PEP 0 @@ -41,6 +42,7 @@ def create_parser(): buildername=args.builder, confoverrides=config_overrides, warningiserror=args.fail_on_warning, + parallel=args.jobs, ) app.builder.copysource = False # Prevent unneeded source copying - we link direct to GitHub app.build() From 23a4207b3fc8fe25bc190f0f5586f59b38c8a888 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Fri, 7 May 2021 14:17:39 +0100 Subject: [PATCH 08/10] Remove non-existent Makefile target --- Makefile | 9 --------- 1 file changed, 9 deletions(-) diff --git a/Makefile b/Makefile index ddd70e96981..140b644aa4f 100644 --- a/Makefile +++ b/Makefile @@ -71,12 +71,3 @@ fail_on_warning: check_links: $(SPHINX_BUILD) --builder linkcheck - -sphinx_package: all rss - mkdir -p package/peps - $(PYTHON) package.py - cp pep-*.txt build/peps/ - cp pep-*.rst build/peps/ - cp *.png build/peps/ - cp *.rss package/peps - tar -C package -czf package/peps.tar.gz peps From dc236e085dae8460cc538b13df71683afa8cd37e Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Fri, 7 May 2021 14:18:16 +0100 Subject: [PATCH 09/10] Update deploy script --- .github/workflows/deploy-gh-pages.yaml | 5 +++-- build.py | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml index fec3f7156ae..dda95fead8b 100644 --- a/.github/workflows/deploy-gh-pages.yaml +++ b/.github/workflows/deploy-gh-pages.yaml @@ -37,5 +37,6 @@ jobs: - name: 🚀 Deploy to GitHub pages uses: JamesIves/github-pages-deploy-action@4.1.1 with: - BRANCH: gh-pages # The branch the action should deploy to. - FOLDER: build # The folder the action should deploy. + branch: gh-pages # The branch to deploy to. + folder: build # Synchronise with build.py -> build_directory + single-commit: true # Delete existing files diff --git a/build.py b/build.py index e5c1f418143..64e0e50983e 100644 --- a/build.py +++ b/build.py @@ -27,7 +27,7 @@ def create_parser(): root_directory = Path(".").absolute() source_directory = root_directory - build_directory = root_directory / "build" + build_directory = root_directory / "build" # synchronise with deploy-gh-pages.yaml -> deploy step doctree_directory = build_directory / ".doctrees" config_overrides = {} From 64605e91d7e09a1a1e4c79143010e70967cdbad8 Mon Sep 17 00:00:00 2001 From: AA Turner <9087854+AA-Turner@users.noreply.github.com> Date: Fri, 7 May 2021 15:53:51 +0100 Subject: [PATCH 10/10] Build to directories by default --- Makefile | 2 +- build.py | 12 +++++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 140b644aa4f..930ff31a04a 100644 --- a/Makefile +++ b/Makefile @@ -70,4 +70,4 @@ fail_on_warning: $(SPHINX_BUILD) --fail-on-warning check_links: - $(SPHINX_BUILD) --builder linkcheck + $(SPHINX_BUILD) --check-links diff --git a/build.py b/build.py index 64e0e50983e..bd615eb1493 100644 --- a/build.py +++ b/build.py @@ -8,8 +8,8 @@ def create_parser(): parser = argparse.ArgumentParser(description="Build PEP documents") - # builders: - parser.add_argument("-b", "--builder", default="html", choices=("html", "dirhtml", "linkcheck")) + # alternative builders: + parser.add_argument("-l", "--check-links", action="store_true") # flags / options parser.add_argument("-f", "--fail-on-warning", action="store_true") @@ -30,6 +30,12 @@ def create_parser(): build_directory = root_directory / "build" # synchronise with deploy-gh-pages.yaml -> deploy step doctree_directory = build_directory / ".doctrees" + # builder configuration + sphinx_builder = "dirhtml" + if args.check_links: + sphinx_builder = "linkcheck" + + # other configuration config_overrides = {} if args.nitpicky: config_overrides["nitpicky"] = True @@ -39,7 +45,7 @@ def create_parser(): confdir=source_directory, outdir=build_directory, doctreedir=doctree_directory, - buildername=args.builder, + buildername=sphinx_builder, confoverrides=config_overrides, warningiserror=args.fail_on_warning, parallel=args.jobs,