sphinx-docs-sync

name	sphinx-docs-sync
description	Two-way comparison and synchronization of Sphinx documentation against the upstream `kdeldycke/repomatic` reference (the default in downstream repos) or across sibling projects. Discovers discrepancies in conf.py, install.md, index.md toctree, pyproject.toml docs dependencies, extra-deps sections, readme badges, and static assets. Use when you want to align documentation structure, catch stale dependencies, or push improvements across your Sphinx-enabled repositories.
compatibility	Designed for Claude Code. Recommended model: Sonnet.
allowed-tools	Bash Read Grep Glob Agent
argument-hint	[path-or-github-url ...]

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

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 sphinx_issues, 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, executables 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 and confirm the regenerator script (docs/docs_update.py) follows the same shape across projects.
• Auto-region marker naming (agent § Auto-generated reference tables, marker naming convention). Grep all docs/*.md for <!-- start -->/ pairs; flag any bare markers, recommend renaming to . Confirm that named markers across siblings use consistent slugs (, , , , , , , ).

Compare and report

Present findings as tables organized by category:

### Category name

| Issue | Severity | Direction | Projects |
|:------|:---------|:----------|:---------|
| description (cite agent § X) | bug/align/enhance | borrow/push | list |

Group, in this order:

1. Bug fixes (stale deps, missing declared deps, broken links).
2. Structural alignment (toctree, page naming, conf.py settings).
3. Content improvements (install.md sections, extra-deps tables, badges).

For each row, name the agent section that authorizes the change (e.g., "agent § Standard page roster: docs/agents toctree entry missing"). If a discrepancy doesn't map to any agent section, flag it as a candidate for new agent content rather than a fix to push.

Implement

After presenting the report, ask the user which items to apply. When they confirm, group edits by project to minimize context switches.

Procedural guards

These are about how you run the audit, not what counts as a violation:

• Always verify file existence before recommending changes based on cross-project patterns. A "missing" file may not apply (e.g., shell completion only matters for CLI projects; binaries only for projects with nuitka.enabled in [tool.repomatic]).
• When a dependency appears in multiple groups (main, extras, docs), the version may be intentionally loose in one group because it's transitively constrained. Verify before flagging.
• Respect project-specific opt-outs: [tool.repomatic] exclude and include lists are authoritative. A page or component listed in exclude is intentionally absent.
• Never silently bump a version pin. Loose pins are sometimes intentional; tight pins always have a reason. Flag, don't fix.
• Before flagging download-URL or asset-name findings, list the real release assets (gh release view {tag} --json assets). Releases in this lineage attach unversioned alias binaries alongside the version-stamped ones, so releases/latest/download/ links that look impossible against stamped filenames are in fact valid.
• A marker or format deviating from the current convention may already be self-healing: check the generator for a legacy-marker migration shim before reporting drift (repomatic's binaries page auto-migrates legacy binaries-start and binaries-chart-start opens to the bare binaries-chart on next touch).
• Sandboxed sessions usually cannot re-test linkcheck_ignore hosts: network allowlists make denials indistinguishable from real 403s. Hand the probe list to the user or defer to a local sphinx-build -b linkcheck run instead of silently skipping the re-test.

Next steps

Suggest the user run:

• /repomatic-audit for broader workflow and config alignment across the same projects.
• /repomatic-deps to analyze dependency graphs for projects with stale or divergent docs deps.
• Opting into the sphinx-docs agent (repomatic init subagents/sphinx-docs) on any project that drifted significantly — Claude will then auto-load the conventions when working in that repo.