Implement automatic HTML generation (#41)

Add automation via GitHub Actions to generate the specification HTML and
deploy the same to GitHub Pages once merged.

Additionally, rework HTML generation to use Poetry[^1] to set up and
manage a virtual environment used to generate the HTML. This helps
ensure that both local and automated builds are using a uniform
environment.

Note that deployment eschews the `upload-pages-artifact`[^2] action
because the mechanism used here allows us to bundle the files and
correct their permissions in one command. (Additionally, this is done
via the Makefile, which allows the archive to be created locally as well
as via an Action.)

For clarity, the `_ext` directory is renamed to `_extensions`, and the
extensions therein are now "installed" to the Poetry environment.
Additionally, the minimum Sphinx version is now to 6.2 or later, as
that's what's been in use recently and Poetry allows us to be less
"stuck" on what's provided by distributions.

Lastly, the Makefile is now cross platform and it will now work on
Windows as long as a GNU Make (or GNU Make compatible tool) is used.

[^1]: https://python-poetry.org/
[^2]: https://github.com/actions/upload-pages-artifact/

Fixes #40.

Co-authored-by: Matthew Woehlke <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+on:
+  pull_request:
+    types: [synchronize, edited, opened]
+  push:
+    branches: [master]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Poetry
+        run: pipx install poetry
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: poetry
+      - name: Install Environment
+        run: make setup
+      - name: Build Documentation
+        run: make html
+      - name: Archive Documentation
+        run: make archive
+      - name: Upload Archive
+        uses: actions/upload-artifact@v4
+        with:
+          if-no-files-found: error
+          name: github-pages
+          path: ${{github.workspace}}/cps-docs.tar.gz
+  deploy:
+    if: github.event.repository.default_branch == github.ref_name
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -1,2 +1,2 @@
-/site/
-/_ext/__pycache__/
+/_site/
+__pycache__/

Makefile

@@ -1,27 +1,71 @@
-# Makefile for Sphinx documentation
+GNUMAKEFLAGS := --no-builtins --no-builtin-variables
+.SUFFIXES:
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-BUILDDIR      = site
+ifeq ($(OS),Windows_NT)
+--which := where
+--null := nul
+RM := rmdir /s /q
+else
+--which := which
+--null ?= /dev/null
+RM := rm -rf
+endif
+
+POETRY ?= $(shell $(--which) poetry 2> $(--null))
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+ifeq ($(POETRY),)
+$(error Could not find the `poetry` command. \
+	Please make sure you have installed poetry, \
+	and that it is on your system's PATH environment variable. \
+	If you don't have poetry installed, \
+	please visit https://python-poetry.org \
+	for instructions on its installation)
 endif
 
-.PHONY: clean all
+SRCDIR ?= $(dir $(realpath $(firstword $(MAKEFILE_LIST))))
+OUTDIR ?= $(join $(SRCDIR),_site)
+ARCHIVE ?= cps-docs.tar.gz
+SPHINXOPTS ?=
+
+venv := $(notdir $(realpath $(shell $(POETRY) env info --path 2> $(--null))))
+
+archive.flags += --create --gzip --verbose
+archive.flags += --file=$(ARCHIVE)
+archive.flags += --directory=$(OUTDIR)
+ifneq ($(OS),Windows_NT)
+archive.flags += --mode=a+rw
+endif
+
+setup.flags += --with=docs
+
+build.flags += $(if $(BUILDER),-b $(BUILDER),-b html)
+build.flags += $(if $(NOCOLOR),,--color)
+build.flags += $(SPHINXOPTS)
 
-all:
-	$(SPHINXBUILD) -b html $(SPHINXOPTS) . $(BUILDDIR)
-	@echo
-	@echo "Build finished. The HTML pages are in '$(BUILDDIR)'."
+.PHONY: all setup html clean.venv clean.cache clean purge archive publish
+
+all: html
+
+setup:
+	$(POETRY) check
+	$(POETRY) install $(setup.flags)
+
+html: setup
+	$(POETRY) run sphinx-build $(build.flags) "$(SRCDIR)" "$(OUTDIR)"
+
+clean.venv:
+	$(if $(venv),$(POETRY) env remove "$(venv)",@echo "Nothing to do")
+
+clean.cache:
+	$(RM) "$(join $(OUTDIR),.doctrees)"
 
 clean:
-	rm -rf $(BUILDDIR)/*
+	$(RM) "$(OUTDIR)"
+
+purge: clean.venv clean
 
-cache-clean:
-	rm -rf $(BUILDDIR)/.doctrees
+archive: html
+	tar $(archive.flags) .
 
 publish: clean all
 	./publish.sh

conf.py

@@ -4,10 +4,8 @@
 import re
 import sys
 
-sys.path.insert(0, os.path.abspath('_ext'))
-
 # -- General configuration ------------------------------------------------
-needs_sphinx = '5.3'
+needs_sphinx = '6.2'
 extensions = ['cps', 'autosectionlabel']
 
 source_suffix = '.rst'
@@ -16,8 +14,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Common Package Specification'
-copyright = u'2024, Matthew Woehlke'
+project = 'Common Package Specification'
+copyright = '2024, Matthew Woehlke'
 
 version_info = (0, 11, 0)
 release = '.'.join(map(str, version_info))

publish.sh

@@ -1,6 +1,6 @@
 #!/bin/sh -e
 
-cd site
+cd _site
 git diff-index --quiet HEAD -- && exit 0
 
 git add .

pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "cps"
+version = "0.dev"
+description = ""
+authors = ["The CPS Project <@>"]
+readme = "readme.md"
+packages = [
+  { include = "cps.py", from = "_extensions" },
+  { include = "autosectionlabel.py", from = "_extensions" }
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+
+[tool.poetry.group.docs.dependencies]
+python = "^3.10"
+sphinx = ">=6.2,<7.3"
+
+[tool.poetry.plugins."sphinx.builders"]
+cps = "cps"
+autosectionlabel = "autosectionlabel"