Refresh architecture docs and generate a reproducible API reference

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: Documentation checks
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: PapyrusReader/server
+          ref: d01f2196c006824dd4be494b1ed43ff3223cd700
+          path: .server
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.12'
+          enable-cache: true
+      - name: Install Graphviz
+        run: sudo apt-get update && sudo apt-get install -y graphviz
+      - name: Install locked documentation dependencies
+        run: uv sync --locked --extra dev
+      - name: Check API snapshot
+        working-directory: .server
+        run: |
+          uv sync --locked
+          uv run --locked python scripts/export_openapi.py ../_static/openapi.json --check
+      - name: Build documentation
+        run: make build

.github/workflows/deploy.yml

@@ -20,16 +20,19 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - uses: astral-sh/setup-uv@v6
         with:
           python-version: "3.12"
-          cache: pip
+          enable-cache: true
+
+      - name: Install Graphviz
+        run: sudo apt-get update && sudo apt-get install -y graphviz
 
       - name: Install dependencies
-        run: pip install -e .
+        run: uv sync --locked
 
       - name: Build site
-        run: sphinx-build -b html . _build/html
+        run: uv run --locked sphinx-build -W --keep-going -b html . _build/html
 
       - uses: actions/upload-pages-artifact@v3
         with:

Makefile

@@ -1,20 +1,19 @@
-.PHONY: help install install-dev serve build clean lint
+.PHONY: install install-dev serve build clean lint
 
 install:
-	pip install -e .
+	uv sync --locked
 
 install-dev:
-	pip install -e ".[dev]"
+	uv sync --locked --extra dev
 
 serve:
-	sphinx-autobuild . _build/html --port 8000
+	uv run --locked sphinx-autobuild . _build/html --port 8000
 
 build:
-	sphinx-build -b html . _build/html
+	uv run --locked sphinx-build -W --keep-going -b html . _build/html
 
 clean:
 	rm -rf _build/
 
-lint:
-	sphinx-build -b html . _build/html
-	linkchecker _build/html/index.html --check-extern --no-warnings
+lint: build
+	uv run --locked linkchecker _build/html/index.html --check-extern --no-warnings

README.md

@@ -1,39 +1,41 @@
 # Papyrus documentation
 
-The documentation site is built with Sphinx.
+Sphinx publishes the product requirements, current architecture, and API reference.
+Requirements describe intended capabilities; the implementation chapters describe
+current behavior.
 
-## Setup
+## Setup and preview
 
-Use Python 3.12 to match the deployment workflow. Install Graphviz and ensure
-its `dot` executable is on your `PATH` to render the requirement diagrams.
+Install uv, Python 3.12, and Graphviz (`dot` must be on PATH), then run:
 
 ```bash
-python3.12 -m venv .venv
-source .venv/bin/activate
-pip install -e ".[dev]"
+uv sync --locked --extra dev --python 3.12
+make serve
 ```
 
-## Usage
+Preview at <http://127.0.0.1:8000>. `make build` produces `_build/html/` and treats
+Sphinx warnings as failures. `make lint` additionally checks external links.
+The Deploy workflow builds with the same lock and publishes GitHub Pages on master.
 
-Run these commands from the repository root with the virtual environment active.
+## API snapshot
 
-Live preview:
+`_static/openapi.json` is generated from the server revision pinned in
+[the CI workflow](.github/workflows/ci.yml). To refresh it from the corresponding
+server checkout, run there:
 
 ```bash
-make serve
+uv sync --locked
+uv run --locked python scripts/export_openapi.py ../docs/_static/openapi.json
+uv run --locked python scripts/export_openapi.py ../docs/_static/openapi.json --check
 ```
 
-Build the static site:
-
-```bash
-make build
-```
-
-The development server runs at **<http://127.0.0.1:8000>** by default.
-The generated site is written to `_build/html/`.
-
-## Deployment
+The exporter uses deterministic documentation settings and does not start the
+application or connect to a database. Update the CI server revision alongside
+intentional API snapshot changes; CI checks freshness against that revision.
+Deployment-specific API prefixes and debug routes remain documented by each
+server's runtime OpenAPI endpoint.
 
-The [Deploy workflow](.github/workflows/deploy.yml) builds the site with Sphinx
-and deploys `_build/html/` to GitHub Pages when changes are pushed to `master`.
-It can also be run manually from GitHub Actions.
+The [Swagger UI](https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/)
+reference uses version-pinned CDN assets and needs network access. The JSON download
+remains available without them. Request execution is disabled on the documentation
+site; use a running server's API explorer to make requests.

_static/api.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Papyrus REST API</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.33.1/swagger-ui.css">
+</head>
+<body>
+  <p><a href="openapi.json">Download the OpenAPI JSON</a></p>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5.33.1/swagger-ui-bundle.js"></script>
+  <script>
+    window.ui = SwaggerUIBundle({
+      url: 'openapi.json',
+      dom_id: '#swagger-ui',
+      deepLinking: true,
+      filter: true,
+      supportedSubmitMethods: [],
+      validatorUrl: null,
+      defaultModelsExpandDepth: -1
+    });
+  </script>
+</body>
+</html>