[gmuloc]

Description

Improves API object references: 47 links to Python objects now use mkdocs-autorefs identifiers, so authors no longer need to maintain API page paths and fragment names. This covers the five remaining guide pages and one additional link in the shared test-overview snippet; links to the inventory and test overview pages remain ordinary page links.

Simplifies the migration plan to 16 consecutive decisions with rationale and revisit conditions, plus completed work awaiting merge. Removes duplicate and speculative follow-up PRs; no follow-up PRs are currently scheduled. API backlinks remain deferred and curated API pages remain in place.

Uses Zensical 0.0.69, already present on main; this PR has no dependency pin changes. The branch includes current main. The migration plan retains the original 0.0.68 evidence and records the 0.0.69 outcome separately. Markdown exports remain blocked by the documented defects. Browser checks accompany relevant UI or tooling changes; versioned deployment checks apply when deployment or URL behavior changes.

Centralizes the 32 known autorefs identifiers in MD052.ignored_labels and removes all per-file MD052 disables. Ordinary undefined references and unregistered object identifiers still fail lint; the strict docs build validates Python targets. Contributor guidance explains registering new identifiers.

Fixes live snippet rebuilds: live edits to the root README.md and the included examples/anta_runner.py previously left pages stale. Explicit README.md and examples watch paths now rebuild those pages without restarting the server or touching their including Markdown. In-docs snippet and Mermaid watching already worked. The migration plan records the reproduced failures, fix, and qualification results.

Validation

• Clean strict build with Zensical 0.0.69.
• Five live edit/restore probes passed against served HTML: root README, shared CLI help (both dependent pages), inventory snippet, Mermaid source (both embedded copies), and external Python example. Every trial source was restored byte-for-byte. Observed rebuilds were about 0.5 seconds for in-docs snippets and 10 seconds for external sources; this is HTTP output evidence, not browser interaction coverage.
• All 47 source references / 48 rendered occurrences resolve to existing pages and fragments; the method-signature label remains linked. All 18 unique objects appear in the 891-entry Sphinx inventory, and API pages contain no backlink blocks.
• Changed-file and final all-files pre-commit checks. Temporary MD052 probes cover accepted object/defined references and rejected missing/misspelled references.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have run pre-commit for code linting and typing
• I have made corresponding changes to the documentation

Summary by CodeRabbit

• Documentation
  • Updated migration notes with the 0.0.69 baseline, validation results, and revised decision and follow-up tracking.
  • Improved API references across guides and reports, and clarified cache-key design and autorefs linting guidance.
  • Expanded documentation preview watch coverage to include the README and examples.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

• Last reviewed commit: f5bbb0a
• Latest commit, not reviewed: f006e53

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Essentials
• Run ID: 8c018474-aad0-47ef-b9ce-7e2252723ff0

📥 Commits

Reviewing files that changed from the base of the PR and between 0f06058 and f5bbb0a.

📒 Files selected for processing: 2

• .github/zensical-migration.md
• zensical.toml

🚧 Files skipped from review as they are similar to previous changes: 1

• .github/zensical-migration.md

Included review availability: This review used your included allowance. 1 included review remains after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

📝 Walkthrough

The migration plan records the Zensical 0.0.69 baseline, decisions, validation results, and follow-up work. Documentation links now use API cross-references, with markdownlint configuration and contribution guidance updated to support autorefs labels.

Changes: Zensical migration and documentation references

Layer / File(s)	Summary
Migration baseline and follow-up plan .github/zensical-migration.md, zensical.toml	The migration plan records the 0.0.69 baseline, decision register, follow-up plan, and validation results. The watcher list adds README.md and examples.
Documentation API references and lint guidance .github/.markdownlint-cli2.yaml, docs/advanced_usages/*, docs/cli/nrfu.md, docs/contribution.md, docs/reports/anta.md, docs/snippets/api_tests_overview.txt, docs/usage-inventory-catalog.md	Documentation links now use Sphinx or centralized API references. The lint configuration permits specified autorefs labels, and contribution guidance explains the registration requirement.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to f5bbb

The documentation reference and watcher changes have no identified defect that should block merging. Rendered link resolution was not independently verified.

Pre-merge checks: 5

Check name	Status	Explanation
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly summarizes the primary changes: improved API links and live rebuild behavior on Zensical 0.0.69.
Description check		The description includes detailed change context, validation results, and most checklist items. It omits the issue identifier and leaves test-related checklist items unchecked, but the validation sect…

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

Full details: Description check

Explanation

The description includes detailed change context, validation results, and most checklist items. It omits the issue identifier and leaves test-related checklist items unchecked, but the validation section documents extensive build, lint, and rebuild testing.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed]

Merging this PR will not alter performance

✅ 34 untouched benchmarks

---

_{Comparing gmuloc:docs/api-object-autorefs (e2b4f4d) with main (3673bd7)}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[carl-baillargeon]

Please update the zensical-migration guide with current dates, etc. Otherwise LGTM!