Refresh architecture docs and generate a reproducible API reference - #2
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a2d3fee4b8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| - name: Build site | ||
| run: sphinx-build -b html . _build/html | ||
| run: uv run --locked sphinx-build -W --keep-going -b html . _build/html |
There was a problem hiding this comment.
On the ubuntu-latest Pages runner, this job installs only Python dependencies even though requirements/index.rst contains Graphviz-backed needflow diagrams and conf.py selects the Graphviz engine. The checks workflow explicitly installs Graphviz at .github/workflows/ci.yml:26-27, but the deploy workflow does not, and Graphviz is absent from the runner's installed software list. Consequently, rendering emits a missing-dot warning, and the newly added -W makes sphinx-build exit with status 1 on any warning, as specified by the Sphinx CLI documentation, preventing Pages deployment.
Useful? React with 👍 / 👎.
Replace the manually maintained API YAML with deterministic OpenAPI JSON generated from the server revision pinned in CI. The old Sphinx OpenAPI extension recurses indefinitely on the current recursive schemas; use a version-pinned Swagger UI reference with tag filtering, plus a direct JSON download. Request execution is disabled; CDN access is needed for the interactive viewer.
Document the actual FastAPI/PostgreSQL/SQLite/PowerSync stack and distinguish product requirements from released functionality. Preserve the requirements and entity design documents. Commit the uv lockfile, use locked dependencies for preview/deployment, add API freshness checks in PR CI, and make Sphinx warnings fail the build.
Validation: locked dependency installation, a clean Sphinx HTML build with warnings treated as errors, deterministic server export and
--check. Browser inspection confirms all 137 operations are indexed and tag navigation works. The pinned Swagger UI version virtualizes its rendered operation list.The server generator comes from server #7; merge that PR first. No task-plan document is added.