feat(docs): add Sphinx + GitHub Pages deploy workflow

.github/workflows/docs.yml

@@ -0,0 +1,89 @@
+name: Docs
+
+# Builds Sphinx documentation on every push and PR that touches docs/, src/, or
+# this workflow. On pushes to main the rendered site is published to GitHub
+# Pages. PRs only build to verify the docs still compile.
+#
+# One-time setup: in the repository's Settings -> Pages, set Source to
+# "GitHub Actions". Without this, the first run of the deploy job fails on
+# actions/deploy-pages with "Get Pages site failed". This cannot be configured
+# from a workflow. See README.md "Deploying API documentation".
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install package and docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install -r docs/requirements.txt
+
+      - name: Build Sphinx documentation
+        run: sphinx-build -W --keep-going -b html docs _site
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: _site
+          if-no-files-found: error
+
+      - name: Configure GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v5
+
+      - name: Upload GitHub Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: [build]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy Pages artifact
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -70,6 +70,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_autosummary/
+_site/
 
 # PyBuilder
 .pybuilder/

.gitkeep

@@ -0,0 +1 @@
+# .gitkeep file auto-generated at 2026-05-15T07:40:14.625Z for PR creation at branch issue-8-7a513b3d2cbf for issue https://github.com/link-foundation/python-ai-driven-development-pipeline-template/issues/8

CONTRIBUTING.md

@@ -74,6 +74,14 @@ Thank you for your interest in contributing! This document provides guidelines a
    pytest --cov=src --cov-report=term --cov-report=html
    ```
 
+   If you changed public APIs or docstrings, build the documentation locally to
+   make sure Sphinx still renders without warnings:
+
+   ```bash
+   pip install -e ".[docs]"
+   sphinx-build -W --keep-going -b html docs _site
+   ```
+
 5. **Add a changelog fragment**
 
    For any user-facing changes, create a changelog fragment:

README.md

@@ -15,6 +15,7 @@ A comprehensive template for AI-driven Python development with full CI/CD pipeli
 - **CI/CD pipeline**: GitHub Actions CI/CD with Python 3.13
 - **Changelog management**: Scriv for conflict-free changelog (like Changesets in JS)
 - **Release automation**: Automatic PyPI publishing and GitHub releases
+- **API documentation**: Sphinx + GitHub Pages deploy on push to `main`
 
 ## Quick Start
 
@@ -87,11 +88,16 @@ ruff check . && ruff format --check . && mypy src/ && python scripts/check_file_
 .
 ├── .github/
 │   └── workflows/
-│       ├── ci.yml              # CI/CD pipeline configuration
-│       └── release.yml         # Release automation (PyPI + GitHub)
+│       ├── docs.yml            # Sphinx build + GitHub Pages deploy
+│       └── release.yml         # CI checks + release automation (PyPI + GitHub)
 ├── changelog.d/                # Changelog fragments (like .changeset/)
 │   ├── README.md               # Fragment instructions
 │   └── *.md                    # Individual changelog entries
+├── docs/                       # Sphinx documentation source
+│   ├── conf.py                 # Sphinx configuration
+│   ├── index.md                # Documentation landing page
+│   ├── api.md                  # Auto-generated API reference
+│   └── requirements.txt        # Documentation build dependencies
 ├── examples/
 │   └── basic_usage.py          # Usage examples
 ├── scripts/
@@ -181,6 +187,42 @@ The GitHub Actions workflow provides:
 4. **Building**: Package building and validation
 5. **Coverage**: Automatic upload to Codecov
 
+### API Documentation
+
+API documentation is built with [Sphinx](https://www.sphinx-doc.org/) and deployed
+to GitHub Pages on every push to `main`. Pull requests build the docs (without
+deploying) to catch regressions before they merge.
+
+```bash
+# Install docs dependencies
+pip install -e ".[docs]"
+
+# Build locally (output goes to _site/)
+sphinx-build -W --keep-going -b html docs _site
+
+# Preview in a browser
+python -m http.server --directory _site 8000
+```
+
+The Sphinx config in `docs/conf.py` autodiscovers `src/my_package` via
+`sphinx.ext.autodoc` + `sphinx.ext.autosummary` and renders Google-style
+docstrings with `sphinx.ext.napoleon`. When you bootstrap a new repository from
+this template, update `project`, `author`, and the autosummary target in
+`docs/conf.py` and `docs/api.md` to point at your package.
+
+#### Deploying API documentation
+
+The `Docs` workflow (`.github/workflows/docs.yml`) builds on every push and
+pull request, and deploys to GitHub Pages only on `push` to `main` (matching
+the JS and Rust template patterns; see
+[link-foundation/relative-meta-logic#170](https://github.com/link-foundation/relative-meta-logic/pull/170)
+for the bug this guards against).
+
+**One-time setup per repository**: open `Settings → Pages` and set
+`Source = GitHub Actions`. Without this, the first deploy run fails on
+`actions/deploy-pages` with `Get Pages site failed`. This cannot be configured
+from a workflow.
+
 ### Release Automation
 
 The release workflow (`release.yml`) provides:

changelog.d/20260515_000000_issue_8_docs_pages.md

@@ -0,0 +1,5 @@
+### Added
+
+- Sphinx documentation scaffold under `docs/` (Furo theme, autodoc/autosummary, Napoleon for Google-style docstrings, MyST for Markdown).
+- `.github/workflows/docs.yml` builds the docs on every push and pull request and deploys to GitHub Pages on `push` to `main` (closes #8). Matches the deploy gating used by the JS and Rust pipeline templates.
+- `[project.optional-dependencies] docs` group in `pyproject.toml` so `pip install -e ".[docs]"` installs Sphinx, Furo, and MyST in one step.

docs/api.md

@@ -0,0 +1,9 @@
+# API reference
+
+```{eval-rst}
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   my_package
+```

docs/conf.py

@@ -0,0 +1,59 @@
+"""Sphinx configuration for the python-ai-driven-development-pipeline-template docs.
+
+Edit ``project``, ``author``, and the autodoc target package when bootstrapping
+a new repository from this template.
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib import metadata
+from pathlib import Path
+
+# Make ``src/`` importable so autodoc can introspect the package.
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "src"))
+
+project = "my-package"
+author = "Your Name"
+
+try:
+    release = metadata.version("my-package")
+except metadata.PackageNotFoundError:
+    release = "0.0.0"
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+]
+
+autosummary_generate = True
+autodoc_typehints = "description"
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": True,
+}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "furo"
+html_static_path: list[str] = []
+html_title = f"{project} {release}"

docs/index.md

@@ -0,0 +1,21 @@
+# my-package
+
+Welcome to the API documentation for `my-package`, generated from the
+[python-ai-driven-development-pipeline-template](https://github.com/link-foundation/python-ai-driven-development-pipeline-template).
+
+When you bootstrap a new repository from this template, replace this page with
+your own landing content and update [`docs/conf.py`](https://github.com/link-foundation/python-ai-driven-development-pipeline-template/blob/main/docs/conf.py)
+with your project name, author, and the autodoc target package.
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+api
+```
+
+## Indices
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=7.4
+furo>=2024.8.6
+myst-parser>=3.0

pyproject.toml

@@ -35,6 +35,11 @@ dev = [
     "pre-commit>=4.0.0",
     "scriv[toml]>=1.7.0",
 ]
+docs = [
+    "sphinx>=7.4",
+    "furo>=2024.8.6",
+    "myst-parser>=3.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/link-foundation/python-ai-driven-development-pipeline-template"