diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml new file mode 100644 index 000000000..dda95fead --- /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 e6e16dd97..b9c892157 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,5 @@ __pycache__ .vscode *.swp /build +/package +/venv diff --git a/Makefile b/Makefile index 889134e6d..930ff31a0 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 000000000..bd615eb14 --- /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 000000000..34835c38a --- /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