From 353379966d381294200c8d5fbeaa901e1a38d382 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Wed, 9 Jun 2021 00:11:26 +0100
Subject: [PATCH] Sphinx support: add Sphinx core files (#1930)

See #2, #1385 for context. Superseeds #1565.

This is the minimal core Sphinx support part, adding a bare minimum of useful things to get Sphinx to build and deploy, whilst not affecting the current build system. There is no theming or custom parsing needed to properly deal with PEPs.

- `build.py` - build script
- `conf.py` - Sphinx configuration
- `Makefile` - new targets for Sphinx
- `.gitignore` - add ignores for `venv` and `package` directories
- `contents.rst` - Sphinx page to discover all PEPs
- `deploy-gh-pages.yaml` - builds and deploys to github pages
- `requirements.txt`
---
 .github/workflows/deploy-gh-pages.yaml | 42 ++++++++++++++++++++
 .gitignore                             |  2 +
 Makefile                               | 26 ++++++++++---
 build.py                               | 54 ++++++++++++++++++++++++++
 conf.py                                | 37 ++++++++++++++++++
 contents.rst                           | 16 ++++++++
 requirements.txt                       |  3 ++
 7 files changed, 174 insertions(+), 6 deletions(-)
 create mode 100644 .github/workflows/deploy-gh-pages.yaml
 create mode 100644 build.py
 create mode 100644 conf.py
 create mode 100644 contents.rst
 create mode 100644 requirements.txt

diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml
new file mode 100644
index 00000000000..dda95fead8b
--- /dev/null
+++ b/.github/workflows/deploy-gh-pages.yaml
@@ -0,0 +1,42 @@
+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 }}-
+
+      - name: 👷‍ Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: 🔧 Build PEPs
+        run: make pages -j$(nproc)
+
+      - name: 🚀 Deploy to GitHub pages
+        uses: JamesIves/github-pages-deploy-action@4.1.1
+        with:
+          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/.gitignore b/.gitignore
index e6e16dd974f..b9c89215748 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,5 @@ __pycache__
 .vscode
 *.swp
 /build
+/package
+/venv
diff --git a/Makefile b/Makefile
index 889134e6d48..930ff31a04a 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 docutils or 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,20 @@ package: all rss
 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
+	$(SPHINX_BUILD) --index-file
+
+sphinx:
+	$(SPHINX_BUILD)
+
+fail_on_warning:
+	$(SPHINX_BUILD) --fail-on-warning
+
+check_links:
+	$(SPHINX_BUILD) --check-links
diff --git a/build.py b/build.py
new file mode 100644
index 00000000000..bd615eb1493
--- /dev/null
+++ b/build.py
@@ -0,0 +1,54 @@
+"""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:
+    parser.add_argument("-l", "--check-links", action="store_true")
+
+    # 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
+
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = create_parser()
+
+    root_directory = Path(".").absolute()
+    source_directory = root_directory
+    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
+
+    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,
+    )
+    app.builder.copysource = False  # Prevent unneeded source copying - we link direct to GitHub
+    app.build()
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 <title/>
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
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