docs: add ADR-027 on Sphinx API-reference rendering strategy - #260
docs: add ADR-027 on Sphinx API-reference rendering strategy#260hasansezertasan wants to merge 1 commit into
Conversation
|
Warning Review limit reached
Next review available in: 48 minutes Limit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits within each organization. For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![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: 9d22dc8e6c
ℹ️ 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".
| four reference pages, all following one deliberate pattern: when `include_docs` | ||
| is set, `docs/conf.py` shells the **live app object** at build time into a | ||
| gitignored `docs/_generated/` directory (each subprocess runs `check=True`, so a | ||
| failure breaks the build), and the reference page pulls the artifact in. No |
There was a problem hiding this comment.
When this ADR is used to understand or extend the docs architecture, this claimed uniform pattern is incorrect for two of the four references: the configuration page renders autopydantic_settings directly from configuration.rst.jinja, without an _generated artifact or subprocess, while the FastAPI branch imports _web_app and writes the schema in-process in conf.py.jinja. Consequently, neither path is a subprocess using check=True, and the same false uniformity is later used as decision rationale at lines 134–136; describe the shared live-source property without claiming all four shell into _generated.
Useful? React with 👍 / 👎.
1 participant
Summary
Adds ADR-027, an evaluation ADR that extends ADR-006 (which weighed only the CLI generator) to cover all four auto-generated Sphinx reference pages: CLI (Typer), config (pydantic), OpenAPI (web), and AsyncAPI (worker).
Key finding: the CLI and config references are genuinely rendered, but the OpenAPI and AsyncAPI references are today just a raw spec dumped via
literalinclude— that asymmetry is what motivates surveying the ecosystem.What it records
typer … utils docs(ADR-006 precedent oversphinxcontrib-typer).autodoc-pydantic(alternatives offer no advantage).sphinxcontrib-openapi(native rST) is the designated future upgrade — JS/CDN embedders ruled out by offline/CSP posture. OpenAPI 3.1 support flagged as a pilot risk.sphinxcontrib-openapi; prototype an AsyncAPI renderer; decide whether anargparseCLI (currently no reference page) warrants one viasphinx-argparse-cli.No template changes — this ADR records evaluation and direction only.