Sphinx - core

.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