Add: MkDocs documentation site with a generated API reference - #1543
Conversation
|
Warning Review limit reached
Next review available in: 58 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. 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 for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling 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 (11)
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 |
72dbdd9 to
b00c598
Compare
The hand-written Python reference promises that the source is authoritative when the two disagree, which only holds if the source is actually published. This builds docs/ into a searchable site and adds a generated reference for simpler.worker, simpler.task_interface and simpler.orchestrator alongside the curated page, which keeps the things a generator cannot state: the **config keys Worker accepts, CallConfig defaults, and the argument-order footguns. Two build details carry the design. Out-of-tree links. A quarter of the relative links in docs/ leave the tree (132 of 523, most of them citing a source file as evidence), and MkDocs only serves docs_dir, so all of them would 404 on the site. docs/_hooks/ repo_links.py resolves each link against its page and rewrites the ones that escape into permalinks at the ref being built, leaving intra-docs links for MkDocs to validate. The docs stay readable on GitHub, where those relative paths still resolve, with no rewriting of the prose. Strictness. The build runs --strict so a dead intra-docs link, a page missing from nav, or a bad anchor fails CI. griffe also warns about parameters that a docstring describes but the signature does not annotate; those report a source typing gap rather than a doc defect, and annotating them means first establishing what a parameter such as ChipWorker.init's `bins` accepts. docs/_hooks/griffe_filter.py attaches a filter to the strict counter alone, so that one message still prints but does not abort, and every other warning still fails the build. The workflow installs docs/requirements.txt rather than the project. Installing the project would run scikit-build-core and compile the C++ runtime; mkdocstrings reads the API through griffe, which parses statically, so the docs need neither a CANN toolkit nor the built nanobind extension. Verified by building the site in an environment where simpler is not installed at all. A pull request builds the site to prove it still compiles; only main deploys. Pages is enabled for the repository with GitHub Actions as the source, so the site publishes at https://hw-native-sys.github.io/simpler/ on the first push to main carrying this workflow. workflow_dispatch is accepted too, so the site can be republished, or the deploy path exercised, without a code change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 participant
Summary
Builds
docs/into a searchable site (MkDocs + Material) and adds a generated API reference forsimpler.worker,simpler.task_interfaceandsimpler.orchestratorvia mkdocstrings — 98 pages,--strictclean.The generated pages sit alongside the hand-written
python-api.md, not instead of it. The curated page keeps what a generator cannot state: which**configkeysWorkeraccepts,CallConfigdefaults, and the argument-order footguns (Orchestrator.malloc(worker_id, size)vsWorker.malloc(size, worker_id)).Relationship to #1542: that PR adds the docstrings this reference renders. The two are independent — I verified this site builds
--strictclean on plainmainwithout it — but the generated pages are noticeably thinner until it lands. Either order works.The two build details that carry the design
Out-of-tree links. A quarter of the relative links in
docs/leave the tree — 132 of 523, mostly citing a source file as evidence for a claim — and MkDocs only servesdocs_dir, so every one would 404 on the site.docs/_hooks/repo_links.pyresolves each link against its own page and rewrites only the ones that escape, into permalinks at the ref being built. Intra-docs links are left alone so--strictstill validates them. The docs stay readable on GitHub, where those relative paths resolve, with no rewriting of the prose.Validated: all 75 unique rewritten targets exist in the repo, directories get
tree/and filesblob/, and no../src/-style link survives in the output.Strictness.
--strictmakes a dead intra-docs link, a page missing fromnav, or a bad anchor fail CI. griffe additionally warns about parameters a docstring describes but the signature does not annotate — a source typing gap, not a doc defect, and not fixable here without first establishing what e.g.ChipWorker.init'sbinsaccepts.docs/_hooks/griffe_filter.pyattaches a filter to the strict counter alone, so that one message still prints and stays visible but does not abort; every other warning still fails the build. Nine such gaps exist today and are worth a follow-up.The workflow does not build the project
pip install -r docs/requirements.txt, deliberately notpip install .— the latter runs scikit-build-core and compiles the C++ runtime. mkdocstrings reads the API through griffe, which parses statically, so the docs job needs neither a CANN toolkit nor the built nanobind extension.I proved this rather than assuming: the site builds with full API docs in an environment where
simpleris not installed at all. An earlier draft of this PR did use a[docs]extra inpyproject.toml; I dropped it because installing the project unavoidably triggers the cmake build, which would have contradicted the workflow's own comment.A pull request builds the site to prove it compiles; only
maindeploys.GitHub Pages — now enabled
Pages is enabled with GitHub Actions as the source (
build_type: workflow,https_enforced: true, no custom domain), and thegithub-pagesenvironment exists. The site will be at:https://hw-native-sys.github.io/simpler/
It returns 404 until this PR merges, because
deployonly runs offmain.workflow_dispatchis now also accepted, so the site can be republished — or the deploy path exercised — without a code change.The one step not yet end-to-end verified is
deployitself, since it is skipped on pull requests by design. Repo-leveldefault_workflow_permissionsisread, which does not block us — the job declarespages: writeandid-token: writeexplicitly, and that setting only governs the default when a workflow declares nothing. I could not read the org-level Actions policy (403, needsadmin:org), so if the first deploy fails on permissions that is where to look.Rebased onto
mainafter #1542 merged, and re-verified the generated pages now render those docstrings —numeric IPv4,HOST_INLINE, the payload-vs-allocationnbytesnote, and both retryableclose()drain paths all appear in the built HTML.Verification
mkdocs build --strictexits 0 — 98 pages, 12Mmaintoo, i.e. independent of Add: docstrings for the remote-buffer API and Worker lifecycle #1542tree/vsblob/correctdocs/_hooks/anddocs/requirements.txtexcluded from the published outputruff check/ruff format --checkclean on both hooks;markdownlint-cli2clean on the changed markdownOne bug worth recording, caught by validating rather than eyeballing: the first version of the link hook used
lstrip("./"), which also ate the leading dot of dotfile paths and turned.claude/rules/codestyle.mdintoclaude/rules/codestyle.md. That would have shipped 24 silently broken links.