docs: add Sphinx documentation site

Add complete Sphinx-based documentation with sphinx-book-theme including:
- API reference with autodoc for all public classes
- Conceptual guides (architecture, checkpointing, stores, TTL, etc.)
- User guides (getting started, installation, middleware, migration)
- Example notebook integration via copy_notebooks.py
- GitHub Actions workflow for automated deployment to GitHub Pages
- Makefile targets for local docs build and preview

Author: bsbodden

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: latest
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Install project dependencies
+        run: poetry install --all-extras
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Copy example notebooks
+        run: python docs/copy_notebooks.py
+
+      - name: Build documentation
+        run: sphinx-build -b html docs docs/_build/html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -107,6 +107,11 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/examples/checkpoints/
+docs/examples/human_in_the_loop/
+docs/examples/memory/
+docs/examples/middleware/
+docs/examples/react_agent/
 
 # PyBuilder
 .pybuilder/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install format lint test test-all test-sentinel clean redis-start redis-stop check-types check
+.PHONY: install format lint test test-all test-sentinel clean redis-start redis-stop check-types check docs docs-clean docs-serve
 
 install:
 	poetry install --all-extras
@@ -41,6 +41,17 @@ find-dead-code:
 
 check: lint test
 
+docs:
+	python docs/copy_notebooks.py
+	sphinx-build -b html docs docs/_build/html
+
+docs-clean:
+	rm -rf docs/_build
+	rm -rf docs/examples/checkpoints docs/examples/human_in_the_loop docs/examples/memory docs/examples/middleware docs/examples/react_agent
+
+docs-serve: docs
+	python -m http.server 8085 --directory docs/_build/html
+
 clean:
 	find . -type d -name "__pycache__" -exec rm -rf {} +
 	find . -type d -name ".pytest_cache" -exec rm -rf {} +

docs/Makefile

@@ -0,0 +1,19 @@
+# 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/_extension/gallery_directive.py

@@ -0,0 +1,139 @@
+"""A directive to generate a gallery of images from structured data.
+
+Generating a gallery of images that are all the same size is a common pattern in
+documentation, and this can be cumbersome if the gallery is generated
+programmatically. This directive wraps this particular use-case in a helper-
+directive to generate it with a single YAML configuration file.
+"""
+from pathlib import Path
+from typing import Any, Dict, List
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from yaml import safe_load
+
+logger = logging.getLogger(__name__)
+
+
+TEMPLATE_GRID = """
+`````{{grid}} {grid_columns}
+{container_options}
+
+{content}
+
+`````
+"""
+
+GRID_CARD = """
+````{{grid-item-card}} {title}
+{card_options}
+
+{content}
+````
+"""
+
+
+class GalleryDirective(SphinxDirective):
+    """A directive to show a gallery of images and links in a grid."""
+
+    name = "gallery-grid"
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+    option_spec = {
+        "grid-columns": directives.unchanged,
+        "class-container": directives.unchanged,
+        "class-card": directives.unchanged,
+    }
+
+    def run(self) -> List[nodes.Node]:
+        if self.arguments:
+            path_data_rel = Path(self.arguments[0])
+            path_doc, _ = self.get_source_info()
+            path_doc = Path(path_doc).parent
+            path_data = (path_doc / path_data_rel).resolve()
+            if not path_data.exists():
+                logger.warn(f"Could not find grid data at {path_data}.")
+                nodes.text("No grid data found at {path_data}.")
+                return
+            yaml_string = path_data.read_text()
+        else:
+            yaml_string = "\n".join(self.content)
+
+        grid_data = safe_load(yaml_string)
+
+        grid_items = []
+        for item in grid_data:
+            options = {}
+            if "website" in item:
+                options["link"] = item["website"]
+
+            if "class-card" in self.options:
+                options["class-card"] = self.options["class-card"]
+
+            if "img-background" in item:
+                options["img-background"] = item["img-background"]
+
+            if "img-top" in item:
+                options["img-top"] = item["img-top"]
+
+            if "img-bottom" in item:
+                options["img-bottom"] = item["img-bottom"]
+
+            options_str = "\n".join(f":{k}: {v}" for k, v in options.items()) + "\n\n"
+
+            content_str = ""
+            if "header" in item:
+                content_str += f"{item['header']}\n\n^^^\n\n"
+
+            if "image" in item:
+                content_str += f"![Gallery image]({item['image']})\n\n"
+
+            if "content" in item:
+                content_str += f"{item['content']}\n\n"
+
+            if "footer" in item:
+                content_str += f"+++\n\n{item['footer']}\n\n"
+
+            title = item.get("title", "")
+            content_str += "\n"
+            grid_items.append(
+                GRID_CARD.format(
+                    card_options=options_str, content=content_str, title=title
+                )
+            )
+
+        container = nodes.container()
+        container_options = {"gutter": 2, "class-container": "gallery-directive"}
+        if "class-container" in self.options:
+            container_options[
+                "class-container"
+            ] += f' {self.options["class-container"]}'
+        container_options_str = "\n".join(
+            f":{k}: {v}" for k, v in container_options.items()
+        )
+
+        grid_directive = TEMPLATE_GRID.format(
+            grid_columns=self.options.get("grid-columns", "1 2 3 4"),
+            container_options=container_options_str,
+            content="\n".join(grid_items),
+        )
+        self.state.nested_parse([grid_directive], 0, container)
+        container = container.children[0]
+
+        if self.options.get("container-class", []):
+            container.attributes["classes"] += self.options.get("class", [])
+        return [container]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_directive("gallery-grid", GalleryDirective)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }