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`

Author: AA-Turner

.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/[email protected]
+        with:
+          branch: gh-pages # The branch to deploy to.
+          folder: build # Synchronise with build.py -> build_directory
+          single-commit: true # Delete existing files

.gitignore

@@ -10,3 +10,5 @@ __pycache__
 .vscode
 *.swp
 /build
+/package
+/venv

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

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()

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/>

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-*

requirements.txt

@@ -0,0 +1,3 @@
+# Requirements for building PEPs with Sphinx
+sphinx >= 3.5
+docutils >= 0.16