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`
This commit is contained in:
parent
629a8b44b0
commit
353379966d
|
@ -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
|
|
@ -10,3 +10,5 @@ __pycache__
|
|||
.vscode
|
||||
*.swp
|
||||
/build
|
||||
/package
|
||||
/venv
|
||||
|
|
26
Makefile
26
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
|
||||
|
|
|
@ -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()
|
|
@ -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/>
|
|
@ -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-*
|
|
@ -0,0 +1,3 @@
|
|||
# Requirements for building PEPs with Sphinx
|
||||
sphinx >= 3.5
|
||||
docutils >= 0.16
|
Loading…
Reference in New Issue