Docs: add original proposal document

.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

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,39 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'zodbpickle'
+copyright = '2013-2024, ZODB Developers <zope-dev@zope.org>'
+author = 'ZODB Developers'
+
+version = '4.0'
+release = '4.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.intersphinx',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+
+# -- Options for intersphinx extension ---------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}