ci: 'meta'-generated hair to build docs

.github/workflows/tests.yml

@@ -324,7 +324,7 @@ jobs:
         with:
           name: zodbpickle-${{ runner.os }}-${{ matrix.python-version }}.whl
           path: dist/
-      - name: Install zodbpickle 3.13 ${{ matrix.python-version }}
+      - name: Install zodbpickle ${{ matrix.python-version }}
         if: matrix.python-version == '3.13'
         run: |
           pip install -U wheel "setuptools<69"
@@ -379,6 +379,74 @@ jobs:
       with:
         parallel-finished: true
 
+  docs:
+    needs: build-package
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.9"]
+        os: [ubuntu-latest]
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      ###
+      # Caching.
+      # This actually *restores* a cache and schedules a cleanup action
+      # to save the cache. So it must come before the thing we want to use
+      # the cache.
+      ###
+      - name: Get pip cache dir (default)
+        id: pip-cache-default
+        if: ${{ !startsWith(runner.os, 'Windows') }}
+        run: |
+          echo "dir=$(pip cache dir)" >>$GITHUB_OUTPUT
+
+      - name: Get pip cache dir (Windows)
+        id: pip-cache-windows
+        if: ${{ startsWith(runner.os, 'Windows') }}
+        run: |
+          echo "dir=$(pip cache dir)" >> $Env:GITHUB_OUTPUT
+
+      - name: pip cache (default)
+        uses: actions/cache@v4
+        if: ${{ !startsWith(runner.os, 'Windows') }}
+        with:
+          path: ${{ steps.pip-cache-default.outputs.dir }}
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: pip cache (Windows)
+        uses: actions/cache@v4
+        if: ${{ startsWith(runner.os, 'Windows') }}
+        with:
+          path: ${{ steps.pip-cache-windows.outputs.dir }}
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Download zodbpickle wheel
+        uses: actions/download-artifact@v4
+        with:
+          name: zodbpickle-${{ runner.os }}-${{ matrix.python-version }}.whl
+          path: dist/
+      - name: Install zodbpickle
+        run: |
+          pip install -U wheel
+          pip install -U coverage
+          pip install -U  "`ls dist/zodbpickle-*.whl`[docs]"
+      - name: Build docs
+        env:
+          ZOPE_INTERFACE_STRICT_IRO: 1
+        run: |
+          sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
+
   lint:
     needs: build-package
     runs-on: ${{ matrix.os }}

.meta.toml

@@ -2,7 +2,7 @@
 # https://github.com/zopefoundation/meta/tree/master/config/c-code
 [meta]
 template = "c-code"
-commit-id = "8d837c89"
+commit-id = "b4846e99"
 
 [python]
 with-appveyor = true
@@ -11,7 +11,7 @@ with-pypy = true
 with-sphinx-doctests = false
 with-future-python = true
 with-macos = false
-with-docs = false
+with-docs = true
 
 [tox]
 use-flake8 = true
@@ -36,6 +36,7 @@ additional-config = [
 
 [manifest]
 additional-rules = [
+    "include *.yaml",
     "include *.sh",
     "recursive-include patches *.diff",
     "recursive-include src *.c",

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Generated from:
+# https://github.com/zopefoundation/meta/tree/master/config/c-code
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: docs/requirements.txt
+  - method: pip
+    path: .

MANIFEST.in

@@ -7,7 +7,13 @@ include buildout.cfg
 include tox.ini
 include .coveragerc
 
+recursive-include docs *.py
+recursive-include docs *.rst
+recursive-include docs *.txt
+recursive-include docs Makefile
+
 recursive-include src *.py
+include *.yaml
 include *.sh
 recursive-include patches *.diff
 recursive-include src *.c

setup.cfg

@@ -22,6 +22,7 @@ per-file-ignores =
 ignore =
     .editorconfig
     .meta.toml
+    docs/_build/html/_sources/*
 
 [isort]
 force_single_line = True

tox.ini

@@ -11,6 +11,7 @@ envlist =
     py312,py312-pure
     py313,py313-pure
     pypy3
+    docs
     coverage
 
 [testenv]
@@ -76,3 +77,12 @@ deps =
     isort
 commands =
     isort {toxinidir}/src {toxinidir}/setup.py []
+
+[testenv:docs]
+basepython = python3
+skip_install = false
+extras =
+    docs
+commands_pre =
+commands =
+    sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html