Sphinx Docs Sync

Context

![ -f repomatic/__init__.py ] && echo "CANONICAL_REPO" || echo "DOWNSTREAM" ![ -d docs ] && echo "docs/ exists" || echo "No docs/ directory" ![ -f docs/conf.py ] && head -5 docs/conf.py || echo "No docs/conf.py" !ls ../*/docs/conf.py 2>/dev/null | head -20 || echo "No sibling projects with docs/conf.py"

Instructions

You audit Sphinx documentation consistency against a reference: the upstream kdeldycke/repomatic canonical docs when run in a downstream repo, or sibling projects when run inside the canonical repo (see § Discover projects for how the reference is chosen). Find discrepancies in both directions: improvements this project can borrow from the reference, and improvements it can push back.

This skill is the procedure layer; the rule layer is .claude/agents/sphinx-docs.md. It carries the canonical conventions: {click:run} directives, recipes for configuration.md/cli.md/install.md, the standard page roster, conf.py hygiene, MyST/admonition rules, high-frequency lapses. When a discrepancy maps to a rule, cite the agent section so the user reads the rationale alongside the proposed change. When you find a pattern not yet codified, propose adding it to the agent rather than fixing it in each repo independently.

Discover projects

If $ARGUMENTS are provided, each argument is a local directory path or a GitHub repository URL (https://github.com/owner/repo or owner/repo). For GitHub URLs, clone into a tmpdir with gh repo clone.

When no $ARGUMENTS are given, the default reference depends on which repo you are in (the ## Context block reports CANONICAL_REPO or DOWNSTREAM):

• DOWNSTREAM: compare this project's docs/ against the canonical kdeldycke/repomatic reference, cloned into a tmpdir with gh repo clone kdeldycke/repomatic. This is the "align me with the source of truth" default, mirroring how /repomatic-audit treats workflows and configs.
• CANONICAL_REPO (you are inside kdeldycke/repomatic): comparing against kdeldycke/repomatic would diff the repo against itself, so scan the parent directory of the cwd for sibling projects with a docs/conf.py and push conventions outward to them instead.

When scanning siblings, filter out forks: check git remote get-url origin and skip projects whose upstream repo name doesn't match the directory name (a local click/ pointing to a fork of pallets/click). Focus on the user's own projects.

List the discovered projects (or the chosen reference) and confirm with the user before proceeding.

Collect documentation inventory

Build first, and count the warnings. A static read of conf.py and the page tree misses the findings that matter most, because nothing in the source says a module is documented twice or a cross-reference resolves nowhere. Run the project's own builder ([tool.repomatic] sphinx.builder, html unless set) into a scratch directory before touching anything, tally WARNING lines by shape, and keep the log: that baseline is what turns "this page repeats an automodule" into "192 duplicate object descriptions", and it is the only way to prove a proposed change inert. Re-run after applying and diff the distinct unresolved targets, not just the totals, since a count can hold steady while one warning replaces another. The venv usually already carries sphinx-build, so invoke it directly rather than syncing a dependency group and disturbing the project's environment. Settle any "is this setting still needed?" question with the same pair of builds: remove it, rebuild, compare.

For each project, collect (parallelize with sub-Agents when possible). For each artifact, the agent section in parentheses is where the convention lives — diff the project against that section, not against your own preferences.

• docs/conf.py (agent § docs/conf.py hygiene, § Standard extension set). Read the full file. Surface settings present in some projects but missing from others; deprecated/renamed settings; conditional imports for Python versions below the project's floor; read_text() calls without encoding=. Cross-check the extension list against the canonical set; flag projects missing sphinxext.opengraph or sphinxcontrib.mermaid that would benefit from them. Confirm myst_enable_extensions matches the canonical alphabetized list. Verify click_extra.sphinx.myst_docstrings ordering (must precede sphinx_autodoc_typehints) and corresponding click-extra[sphinx] entry in [dependency-groups] docs.
• conf.py warning/strictness governance (agent § suppress_warnings governance, § nitpick_ignore governance, § Linkcheck and intersphinx). Audit each suppress_warnings, nitpick_ignore, and linkcheck_ignore entry: does it carry a comment naming the failing case and the reason for suppression? Flag uncommented entries. Re-test linkcheck-ignored hosts on each audit pass; remove entries that have started working again. Suggest migrating per-anchor linkcheck_anchors_ignore patterns to per-host linkcheck_anchors_ignore_for_url when the entire host is JS-rendered.
• docs/index.md (agent § Standard page roster). Diff toctree shape, page ordering, octicon icons (cross-check against the canonical octicon registry), and presence/absence of standard pages.
• docs/install.md (agent § Recipes › install.md). Diff section roster, install-method tab order, Binaries table format, Repology badge, Python compatibility matrix structure, gh attestation verify section.
• docs/cli.md and docs/configuration.md (agent § Recipes). Diff the auto-region between markers, then compare the regenerator script (docs/docs_update.py) across the projects that still carry one. The agent's recipes render both pages live, so a project with no script has already migrated and is not missing anything.
• Auto-region marker naming (agent § Auto-generated reference tables, marker naming convention). Grep all docs/*.md for <!-- start -->/<!-- end --> pairs; flag any bare markers, recommend renaming to <!-- {feature}-{kind} -->/<!-- {feature}-{kind}-end -->. Confirm that named markers across siblings use consistent {kind} slugs (table, sankey, mindmap, chart, autodata, automodule, autodoc, reference).
• Theme assets (agent § conf.py hygiene › Theme assets and OpenGraph). Confirm the sidebar logo is Furo's light_logo/dark_logo pair in html_theme_options, each name also listed in html_static_path, with html_logo unset — Furo prefers html_logo and skips the pair when it is present, so a lingering html_logo is drift to report, never the thing to confirm. Confirm html_favicon = "assets/favicon.svg", and that ogp_image is _static/banner-social-<variant>.png with that PNG also listed in html_static_path, never a bare assets/... path (docs/assets/ is not copied into the built site, so that value 404s for social crawlers). An absolute raw.githubusercontent.com URL was the earlier rule: it still resolves, so report it as alignment, not as a bug. Flag projects with sphinxext.opengraph enabled but no ogp_image set. Suggest the user run /brand-assets on flagged projects to regenerate or backfill the asset set in one pass.
• sphinx_issues migration (agent § Migrating off sphinx_issues). Grep each project for {issue} /{pr} / {user} /{commit} (MyST) and :issue: /:pr: / :user: /:commit: (reST) across *.md, *.rst, *.py. Flag every occurrence and offer to apply the migration recipe in one pass per repo. After replacement, drop "sphinx_issues" from extensions in conf.py, "sphinx-issues>=…" from [dependency-groups] docs, and any issues_github_path setting unused by other extensions.
• pyproject.toml docs dependency group. Compare against what conf.py actually imports — flag undeclared imports and declared-but-unimported deps. Don't change version pins unless provably stale (a conditional dep on a Python version below the project's floor; a transitively-constrained loose pin held by a meta-extra like click-extra[sphinx]).
• readme.md. Compare badge sets and section structure. Flag developer setup held in a ## Development section or in claude.md: it belongs on the contributing page (per agent § High-frequency lapses).
• Sphinx tests (agent § Sphinx tests). Look for tests/sphinx/, tests/test_sphinx_*.py, or test_sphinx_crossrefs.py. Note which projects have render-tests and which don't; suggest adopting cross-reference render tests where the docs surface complex {role} cross-refs.
• Static assets and auto-generated files. Compare docs/_static/, docs/assets/, .rst files, docs_update.py. Hunt for stale .rst orphans from past package renames.