Implement automatic HTML generation

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

Additionally, rework HTML generation to use Poetry¹ 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`² action because
the mechanism used here allows us to bundle the files and correct their
permissions in one command.

For clarity, the `_ext` directory is renamed to `_extensions`. Also, the
minimum Sphinx version is bumped to 6.2, as that's what's been in use
recently and Poetry allows us to be less "stuck" on what's provided by
distributions.

¹ https://python-poetry.org/
² https://github.com/actions/upload-pages-artifact/

Fixes #40.

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

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+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:
+          cache: poetry
+      - name: Install Environment
+        run: poetry install --with=docs
+      - name: Build Documentation
+        run: >-
+          cd ${{github.workspace}} && make
+      - name: Archive Documentation
+        run: >-
+          tar
+          --create
+          --gzip
+          --verbose
+          --mode=a+rw
+          --file=cps-docs.tar.gz
+          --directory=${{github.workspace}}/_site
+          .
+      - 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/
+/_extensions/__pycache__/

Makefile

@@ -1,9 +1,11 @@
 # Makefile for Sphinx documentation
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+POETRY        = poetry
+POETRYOPTS    =
+SPHINXOPTS    = --color
 SPHINXBUILD   = sphinx-build
-BUILDDIR      = site
+BUILDDIR      = _site
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -13,7 +15,7 @@ endif
 .PHONY: clean all
 
 all:
-	$(SPHINXBUILD) -b html $(SPHINXOPTS) . $(BUILDDIR)
+	$(POETRY) $(POETRYOPTS) run -- $(SPHINXBUILD) -b html $(SPHINXOPTS) . $(BUILDDIR)
 	@echo
 	@echo "Build finished. The HTML pages are in '$(BUILDDIR)'."
 

conf.py

@@ -4,10 +4,10 @@
 import re
 import sys
 
-sys.path.insert(0, os.path.abspath('_ext'))
+sys.path.insert(0, os.path.abspath('_extensions'))
 
 # -- General configuration ------------------------------------------------
-needs_sphinx = '5.3'
+needs_sphinx = '6.2'
 extensions = ['cps', 'autosectionlabel']
 
 source_suffix = '.rst'
@@ -16,8 +16,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, 10, 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,14 @@
+[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"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+sphinx = ">=6.2,<7.3"