Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

sphinx-docs-sync

/sphinx-docs-sync

Porównuje dokumentację Sphinx z repozytorium referencyjnym i wyrównuje conf.py, spis treści, zależności, odznaki i zasoby statyczne.

Repozytorium
repomatic ↗
Licencja
LGPL
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
4
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

LGPL, otwarta.

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (4). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Porównuje dokumentację Sphinx z repozytorium referencyjnym i wyrównuje conf.py, spis treści, zależności, odznaki i zasoby statyczne.

Argumenty

/sphinx-docs-sync [path-or-github-url ...]
Oryginalny opis (EN)

Compare and synchronize Sphinx documentation against the upstream `kdeldycke/repomatic` reference, or across sibling projects. Downstream repos compare against upstream by default. Find the differences in conf.py, install.md, the index.md toctree, pyproject.toml docs dependencies, extra-deps sections, readme badges and static assets. Use when you align documentation structure, catch stale dependencies, or push improvements across Sphinx-enabled repositories.

Jak działa

  1. Context
  2. Instructions
Sekcje z nagłówków SKILL.md, w oryginale · 93 linii, 1 656 słów
Podgląd SKILL.md
---
name: sphinx-docs-sync
description: Compare and synchronize Sphinx documentation against the upstream `kdeldycke/repomatic` reference, or across sibling projects. Downstream repos compare against upstream by default. Find the differences in conf.py, install.md, the index.md toctree, pyproject.toml docs dependencies, extra-deps sections, readme badges and static assets. Use when you align documentation structure, catch stale dependencies, or push improvements across 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

**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` roles** (agent § Standard extension set). Grep each project for `{issue}` `/`{pr}` ` / `{user}` `/`{commit}` ` (MyST) and `:issue:` `/`:pr:` ` / `:user:` `/`:commit:` ` (reST) across `*.md`, `*.rst`, `*.py`. Flag every occurrence, and recommend an explicit GitHub URL in its place. Once none is left, 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.

### 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/subagents 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.
- Adding a docs dependency to `pyproject.toml` is half the change: every workflow here installs with `uv run --frozen`, so an unregenerated `uv.lock` fails the docs job on the next push. Re-lock in the same pass, with `XDG_CONFIG_HOME` pointed at an empty directory so a machine-wide `uv.toml` cannot write its own `exclude-newer-package` entries into the project's lockfile. Never reach for `--no-config`, which discards the project's `[tool.uv]` along with it.
- 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.
- 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.

Wersje

RepozytoriumWynikLicencja
Ta strona · kdeldycke/repomatic100LGPL
kdeldycke/dotfiles100BSD-2-Clause

Migawka bazy z 13.11.2026 · wersja paczki 9599ae7d0078 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100code-docstrings-api-reference-generation-typedoc-sphinx
    Generuje dokumentację API z komentarzy w kodzie przez TypeDoc i Sphinx.
  • 100litestar-docs
    Pomaga przygotować dokumentację Litestar i referencję API w Sphinx, mkdocstrings i zensical.
  • 100api-docs
    Stosuje konwencje dokumentacji API przy plikach Sphinx: conf.py, struktura RST, integracja Doxygen i Breathe dla C++, środowiska tox i wrappery Makefile.
  • 96docs
    Aktualizuje dokumentację Konstruct w Sphinx i MyST oraz README, gdy zmienia się polecenie, opcja, wynik albo liczba.
  • 95documenting-python-libraries
    Pisze dokumentację biblioteki Python: docstringi w stylu Google, konfigurację Sphinx, referencje API i poradniki.
  • 100scientific-documentation
    Konfiguruje i utrzymuje dokumentację naukowych pakietów Pythona: Sphinx, MkDocs, docstringi w stylu NumPy, framework Diataxis, dostępność i hosting na Read the Docs.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.