DOC: Replace API_MAP with graphify and fix Sphinx warnings - #105
Conversation
Remove the docs/API_MAP.md generator and every reference to it. The generated map duplicated what the graphify knowledge graph already provides, and its pre-commit hook regenerated a gitignored file on every Python change. - Delete utils/generate_api_map.py and the /regen-api-map skill - Drop the generate-api-map pre-commit hook - Point CLAUDE.md, AGENTS.md, .agents/ agents and skills, developer docs, tutorials/README.md, and statistics.md at graphify instead - Add docs/developer/ai_assistants.rst recommending graphify for AI coding, linked from contributing.rst and the Developer Guides toctree Also fix four pre-existing Sphinx diagnostics that were masking real rendering bugs: - architecture.rst: two-line definition-list terms rendered their bodies as block quotes; join each term onto one line - RegisterTimeSeriesImages: missing blank lines before two lists made them render as run-on paragraphs - AnatomyGroup: autodoc and napoleon each documented the dataclass fields; use :no-members: so they appear once - api/utilities: two nav links pointed at a nonexistent nrrd_conversion page; repoint to image_conversion
|
Warning Review limit reached
Next review available in: 47 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 (2)
WalkthroughThe repository replaces generated API-map workflows with Graphify guidance and updates contributor documentation. It also corrects API navigation, tutorial references, and documentation formatting. ChangesGraphify documentation workflow
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
There was a problem hiding this comment.
Pull request overview
This PR removes the legacy docs/API_MAP.md generation workflow (and its pre-commit regeneration hook) in favor of using the existing graphify-out/ knowledge graph for codebase navigation, while also fixing several Sphinx documentation diagnostics that were masking rendering issues.
Changes:
- Delete
utils/generate_api_map.pyand remove thegenerate-api-mappre-commit hook. - Update contributor/agent/developer docs to reference
graphify query/.../updateinstead ofdocs/API_MAP.md. - Fix Sphinx rendering issues (definition-list terms, list spacing,
AnatomyGroupmember duplication, and broken nav links).
Reviewed changes
Copilot reviewed 27 out of 27 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
utils/generate_api_map.py |
Removes the API map generator script. |
tutorials/README.md |
Updates contributor API reference links and points AI navigation to graphify docs. |
statistics.md |
Replaces API map references with Sphinx API docs / graphify. |
src/physiotwin4d/register_time_series_images.py |
Fixes RST list rendering by adding required blank lines in docstring. |
docs/index.rst |
Adds the new developer guide page to the docs toctree. |
docs/developer/workflows.rst |
Replaces API map regeneration step with graphify update .. |
docs/developer/extending.rst |
Replaces API map guidance with graphify refresh guidance. |
docs/developer/core.rst |
Removes API map references; adds graphify refresh instructions. |
docs/developer/ai_assistants.rst |
New page describing AI-assistant conventions and graphify usage. |
docs/contributing.rst |
Adds a short callout recommending graphify for AI-assisted navigation. |
docs/conf.py |
Removes API_MAP.md from Sphinx exclude patterns. |
docs/architecture.rst |
Fixes definition-list term wrapping that caused block-quote rendering. |
docs/api/utilities/test_tools.rst |
Fixes navigation link to point to image_conversion. |
docs/api/utilities/contour_tools.rst |
Fixes navigation link to point to image_conversion (but currently drops test_tools). |
docs/api/segmentation/base.rst |
Uses :no-members: for AnatomyGroup to avoid duplicate field docs. |
docs/.gitignore |
Stops gitignoring API_MAP.md (since it’s removed). |
CLAUDE.md |
Removes API map references; drops /regen-api-map mentions. |
AGENTS.md |
Adds a graphify section and replaces API map guidance with graphify guidance. |
.pre-commit-config.yaml |
Removes the local generate-api-map hook. |
.agents/skills/simplify-staged/SKILL.md |
Updates “check API map” guidance to “check with graphify query”. |
.agents/skills/regen-api-map/SKILL.md |
Deletes the regen skill documentation. |
.agents/skills/plan/SKILL.md |
Replaces API map lookup instruction with graphify query. |
.agents/skills/impl/SKILL.md |
Replaces API map lookup instruction with graphify query. |
.agents/skills/doc-feature/SKILL.md |
Replaces API map regeneration instruction with graphify refresh instruction. |
.agents/agents/implementation.md |
Replaces API map mention with graphify query guidance. |
.agents/agents/docs.md |
Replaces API map mentions with graphify refresh guidance (but contains a quoting-style inconsistency). |
.agents/agents/architecture.md |
Replaces API map mention with graphify query guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/developer/ai_assistants.rst (1)
19-45: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDocument one clean-checkout Graphify workflow.
The affected documentation requires Graphify, but
statistics.mdstates thatgraphify-out/is not checked in. Verify that the supported environment provides thegraphifyexecutable and document graph initialization. If Graphify is optional, make the commands conditional and retain manual search as the fallback.
docs/developer/ai_assistants.rst#L19-L45: add installation, initialization, and fallback instructions.AGENTS.md#L102-L120: distinguish generated local output from checked-in repository content.AGENTS.md#L156-L157: require Graphify queries only when the graph exists.docs/contributing.rst#L54-L56: link contributors to the setup and fallback procedure.docs/developer/core.rst#L58-L63: link the API-change procedure to the same setup and fallback.docs/developer/extending.rst#L64-L65: link the public-API procedure to the same setup and fallback.tutorials/README.md#L92-L96: retain a usable fallback for contributors without Graphify.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/developer/ai_assistants.rst` around lines 19 - 45, Document a clean-checkout Graphify workflow in docs/developer/ai_assistants.rst, including verifying or installing the graphify executable, initializing graphify-out/, and using manual search when Graphify is unavailable. Update AGENTS.md at lines 102-120 to distinguish generated local output from checked-in content and at lines 156-157 to require queries only when the graph exists. Link the same setup and fallback procedure from docs/contributing.rst lines 54-56, docs/developer/core.rst lines 58-63, and docs/developer/extending.rst lines 64-65; retain a usable non-Graphify fallback in tutorials/README.md lines 92-96.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/doc-feature/SKILL.md:
- Around line 16-17: Update the Graphify guidance in the documented workflow to
require running `graphify update .` after any public API change, not only
changes to public class, method, or function signatures. Include changes to
public behavior and public attributes, while preserving the existing command and
placement in the workflow.
In `@docs/api/utilities/contour_tools.rst`:
- Line 18: Update the documentation navigation line to retain the existing
test_tools entry while replacing only the obsolete nrrd_conversion link with
image_conversion, preserving the transform_tools and index entries.
In `@docs/developer/workflows.rst`:
- Line 55: Update the workflow step describing when to run ``graphify update .``
so it says “after public API changes” instead of “after exposing public
methods,” covering additions, modifications, and removals of public methods.
---
Nitpick comments:
In `@docs/developer/ai_assistants.rst`:
- Around line 19-45: Document a clean-checkout Graphify workflow in
docs/developer/ai_assistants.rst, including verifying or installing the graphify
executable, initializing graphify-out/, and using manual search when Graphify is
unavailable. Update AGENTS.md at lines 102-120 to distinguish generated local
output from checked-in content and at lines 156-157 to require queries only when
the graph exists. Link the same setup and fallback procedure from
docs/contributing.rst lines 54-56, docs/developer/core.rst lines 58-63, and
docs/developer/extending.rst lines 64-65; retain a usable non-Graphify fallback
in tutorials/README.md lines 92-96.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 69cd2d18-1947-4f99-8e42-fa1bcbf10163
📒 Files selected for processing (27)
.agents/agents/architecture.md.agents/agents/docs.md.agents/agents/implementation.md.agents/skills/doc-feature/SKILL.md.agents/skills/impl/SKILL.md.agents/skills/plan/SKILL.md.agents/skills/regen-api-map/SKILL.md.agents/skills/simplify-staged/SKILL.md.pre-commit-config.yamlAGENTS.mdCLAUDE.mddocs/.gitignoredocs/api/segmentation/base.rstdocs/api/utilities/contour_tools.rstdocs/api/utilities/test_tools.rstdocs/architecture.rstdocs/conf.pydocs/contributing.rstdocs/developer/ai_assistants.rstdocs/developer/core.rstdocs/developer/extending.rstdocs/developer/workflows.rstdocs/index.rstsrc/physiotwin4d/register_time_series_images.pystatistics.mdtutorials/README.mdutils/generate_api_map.py
💤 Files with no reviewable changes (5)
- docs/conf.py
- docs/.gitignore
- .pre-commit-config.yaml
- utils/generate_api_map.py
- .agents/skills/regen-api-map/SKILL.md
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #105 +/- ##
=======================================
Coverage 35.61% 35.61%
=======================================
Files 64 64
Lines 8277 8277
=======================================
Hits 2948 2948
Misses 5329 5329
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.
Suppressed comments (1)
CLAUDE.md:126
- This PR introduces a new documentation/testing policy (“do not restate shape, axis order, or world space in docstrings, comments, or test docstrings”) that is not mentioned in the PR description, which otherwise frames the change as API_MAP→graphify + Sphinx warning fixes. If this policy change is intentional, it should be explicitly called out in the PR description (or split into a separate PR) since it changes contributor guidance and affects multiple agent skills/docs.
These conventions are fixed and hold everywhere, so this list is their single
source of truth — do not restate shape, axis order, or world space in
docstrings, comments, or test docstrings. Document only genuine deviations,
such as a raw NumPy array whose axes are reversed relative to the ITK image it
came from.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
AGENTS.md (1)
156-157: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winDefine one Graphify availability rule.
These instructions require
graphify querywithout a fallback whengraphify-out/graph.jsonis absent. Use Graphify when the graph exists. Use manual search when it does not.
AGENTS.md#L156-L157: add the Graphify availability condition and manual-search fallback..agents/agents/implementation.md#L17-L18: apply the same condition before manual symbol searches..agents/skills/simplify-staged/SKILL.md#L48-L49: apply the same condition to the reuse check.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` around lines 156 - 157, Define one Graphify availability rule across AGENTS.md:156-157, .agents/agents/implementation.md:17-18, and .agents/skills/simplify-staged/SKILL.md:48-49: use graphify query only when graphify-out/graph.json exists, and otherwise fall back to manual search; apply this condition respectively to graph navigation, implementation symbol searches, and the simplify-staged reuse check.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/check-conventions/SKILL.md:
- Around line 60-61: Update the checklist rule in SKILL.md to flag any docstring
or comment that restates fixed ITK shape, axis order, or LPS world-space
conventions, regardless of whether it also documents parameters or return
values; remove the limiting “instead of” condition.
In `@AGENTS.md`:
- Around line 176-179: Update the later coordinate-transform rule in AGENTS.md
to use LPS-to-Y-up terminology, unless it explicitly describes a separate RAS
input boundary. Ensure the ITK/PyVista boundary guidance consistently
distinguishes the internal LPS frame from the export conversion.
---
Outside diff comments:
In `@AGENTS.md`:
- Around line 156-157: Define one Graphify availability rule across
AGENTS.md:156-157, .agents/agents/implementation.md:17-18, and
.agents/skills/simplify-staged/SKILL.md:48-49: use graphify query only when
graphify-out/graph.json exists, and otherwise fall back to manual search; apply
this condition respectively to graph navigation, implementation symbol searches,
and the simplify-staged reuse check.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: efbb5ac0-c77b-4b92-ae17-7fe8febbf2dd
📒 Files selected for processing (12)
.agents/agents/docs.md.agents/agents/implementation.md.agents/agents/testing.md.agents/skills/check-conventions/SKILL.md.agents/skills/doc-feature/SKILL.md.agents/skills/plan/SKILL.md.agents/skills/simplify-staged/SKILL.md.agents/skills/test-feature/SKILL.mdAGENTS.mdCLAUDE.mddocs/cli_scripts/byod_tutorials.rstdocs/developer/workflows.rst
🚧 Files skipped from review as they are similar to previous changes (4)
- .agents/skills/doc-feature/SKILL.md
- .agents/skills/plan/SKILL.md
- docs/developer/workflows.rst
- CLAUDE.md
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.
Suppressed comments (2)
docs/api/utilities/contour_tools.rst:18
- The utilities navigation line no longer links to
test_tools. The PR description only mentions repointingnrrd_conversiontoimage_conversion, so this looks like an accidental drop and makes it harder to hop from contour utilities to the testing helpers (still listed indocs/api/utilities/index.rst).
:doc:`transform_tools` | :doc:`index` | :doc:`image_conversion`
docs/conf.py:68
docs/API_MAP.mdis no longer gitignored, but existing clones may still have a stale untrackeddocs/API_MAP.mdfrom before this PR. Since.mdis a Sphinx source suffix here, that file can reintroduce Sphinx warnings in local builds. Keeping it inexclude_patternsavoids regressing localmake htmlfor contributors who haven't deleted the old file yet.
"README.md",
Remove the docs/API_MAP.md generator and every reference to it. The generated map duplicated what the graphify knowledge graph already provides, and its pre-commit hook regenerated a gitignored file on every Python change.
Also fix four pre-existing Sphinx diagnostics that were masking real rendering bugs:
Summary by CodeRabbit
Documentation
Chores