agentsclimarketplace

Audit docs

Skill UMEP-dev/SUEWS/.claude/skills/audit-docs

Documentation sanity check for SUEWS source files. Two checks under one roof - non-ASCII characters in sphinx-gallery tutorials/RST/docstrings (with context-aware RST/LaTeX/matplotlib replacement), and bibliography topic-tag convention plus metadata backfill on the refs bib files. Use when editing docs/source files or the refs-*.bib files, when a doc hook flags an issue, or when asked to "audit docs", "check docs", "fix non-ASCII", "check bib tags", "curate refs". Complements sync-docs (doc-code content consistency) and lint-code (code style).From its SKILL.md

Install
npx -y skills add UMEP-dev/SUEWS --skill audit-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

6.1 KB, as published. Nobody here has run it

audit-docs

A single docs sanity-check entry point. It bundles the two mechanical, deterministic documentation checks that the doc-change hooks point at:

  • ASCII / markup -- non-ASCII characters in documentation source, replaced with context-appropriate RST / LaTeX / matplotlib markup.
  • References -- bibliography topic-tag convention on the SUEWS bib files, plus optional metadata (abstract) backfill.

For doc-code content consistency (signatures, parameters, values) use sync-docs; for code style use lint-code. This skill is the fast, rule-based hygiene pass, suited to running on every documentation edit.

Triggers

  • Editing docs/source/** (.py tutorials, .rst, docstrings) or docs/source/assets/refs/refs-SUEWS.bib / refs-community.bib.
  • A doc hook reports an issue (check-doc-ascii.sh, check-bib-tags.sh).
  • "audit docs", "check docs", "fix non-ASCII in tutorials", "check bib tags", "verify topic slugs", "curate refs".
  • /audit-docs, /audit-docs ascii <path>, /audit-docs refs.

Modes

  • ascii -- scan and fix non-ASCII characters (default for docs/source/**).
  • refs -- audit bib topic-tags and optionally enrich metadata.
  • all -- run both (default when no mode and no path is given).

ASCII / markup check

Enforce ASCII-only output in documentation source per .claude/rules/00-project-essentials.md. Sphinx-gallery .py tutorials need special handling: comments become RST prose, print statements become terminal output, and matplotlib strings render via LaTeX -- each context takes a different replacement.

Workflow

  1. Scan target files for non-ASCII characters.
    grep -rPn '[^\x00-\x7F]' docs/source/tutorials/tutorial_*.py
    
    If a specific file is given as argument, scan only that file. (On macOS the doc hook uses perl instead of grep -P; either works.)
  2. Classify each occurrence by context (see references/replacement-rules.md).
  3. Replace using context-appropriate markup.
  4. Verify no non-ASCII remains:
    grep -rPn '[^\x00-\x7F]' <scanned files>
    
  5. Report changes made.

Output

[audit-docs:ascii] Analysis

=== docs/source/tutorials/tutorial_03_initial_conditions.py ===
  L35: [RST comment] m^2/m^2 -> :math:`m^2/m^2`  (superscript 2)
  L193: [matplotlib] m^2/m^2 -> m$^2$/m$^2$  (superscript 2)

Summary: 1 file, 2 replacements, 0 non-ASCII remaining

References check

Enforce the topic-tag convention (every entry in the SUEWS bib files carries a valid slug from the controlled vocabulary in .claude/rules/docs/bib-topic-tags.md) and backfill missing metadata. Pairs with docs/source/related_publications.rst, which renders per-topic subsections via sphinxcontrib-bibtex's :filter: on the keywords field.

Scope

  • Checks convention compliance: every entry has a keywords field, every slug is in the approved vocabulary, slug format is lowercase-hyphen, no duplicate citation keys, and required fields are present. Every entry requires title, author, and year; all entry types other than @unpublished also require doi. An @unpublished entry instead requires a publication-status note (for example, In preparation or Under review) and may omit doi. Missing abstracts are reported as informational warnings, not failures.
  • Does not verify DOI-to-paper correctness -- use the user-level refs-checker skill for that.

Base audit (no network, no API key)

uv run --no-project --with requests python .claude/skills/audit-docs/scripts/audit.py \
    docs/source/assets/refs/refs-SUEWS.bib \
    docs/source/assets/refs/refs-community.bib

Exit code is non-zero on any convention violation. Missing abstracts are warnings only.

Enrichment (WoS/Crossref)

Populate missing abstract fields in place. Idempotent.

# With a WoS key (WOS_EXPANDED_API_KEY or WOS_API_KEY in env)
uv run --no-project --with requests python .claude/skills/audit-docs/scripts/enrich.py \
    docs/source/assets/refs/refs-SUEWS.bib \
    docs/source/assets/refs/refs-community.bib

# Without a WoS key (collaborators)
uv run --no-project --with requests python .claude/skills/audit-docs/scripts/enrich.py \
    docs/source/assets/refs/refs-SUEWS.bib \
    docs/source/assets/refs/refs-community.bib \
    --crossref-only

Cascade: WoS Expanded -> WoS Starter -> Crossref -> OpenAlex. Flags: --crossref-only (skip WoS), --dry-run (report sources only), --delay SECONDS (default 0.3).

Controlled vocabulary

Source of truth: .claude/rules/docs/bib-topic-tags.md. Kept in sync with the header comment of both bib files and the VOCAB set in scripts/audit.py. Expanding the vocabulary is a four-file edit documented in the rule.


Hooks

These run automatically on documentation edits and point back here:

  • check-doc-ascii.sh (PostToolUse, Edit/Write) -- scans docs/source/**.{py,rst,md} for non-ASCII and blocks the edit on a hit.
  • check-bib-tags.sh (PostToolUse, Edit/Write) -- runs scripts/audit.py on edits to docs/source/assets/refs/*.bib.

References

  • references/replacement-rules.md - Full non-ASCII replacement table by context.
  • scripts/audit.py - Bib topic-tag convention audit.
  • scripts/enrich.py - Bib metadata (abstract) backfill.
  • .claude/rules/00-project-essentials.md - ASCII-only rule.
  • .claude/rules/docs/bib-topic-tags.md - Topic-tag convention and vocabulary.

Complementary skills

  • sync-docs - doc-code content consistency (deeper, on-demand).
  • lint-code - code style and RST formatting.
  • refs-checker (user-level) - DOI-to-paper metadata correctness.

Keep looking

Skills are one crate of 614,194. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.