mcpField
R
rewrite-python-docs

rewrite-python-docs

github.com/liblafDevelopment0184 installsUpdated 4d ago
Repository

About rewrite-python-docs

rewrite-python-docs is a skill for rewriting Python project documentation from the source code outward. It guides maintainers through updating docs and docstrings while validating generated references and builds.

Key features

  1. 01Source-first documentation review
  2. 02Guidance for rewriting docs and docstrings
  3. 03Generated reference-page workflow
  4. 04Doctest and documentation validation

Use cases

  1. 01Revising outdated Python package documentation
  2. 02Adding runnable examples to public API docs
  3. 03Checking documentation changes before merging

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/liblaf/skills --skill rewrite-python-docs

After installing, type/rewrite-python-docsin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
google-style.md
scripts/
gen-ref-pages.py

Details

From the project README

Rewrite Python Docs

Use source code as the source of truth. Treat existing docs, docstrings, tests, and examples only as weak hints.

Guidelines

  • Inspect pyproject.toml, zensical.toml, noxfile.py, .config/mise/, public exports, source code, and tests before editing.
  • Run scripts/gen-ref-pages.py to regenerate reference pages under docs/reference/. The script will output a navigation table that can be copy-pasted into zensical.toml.
  • Files to update:
    • docstrings in source code
    • docs/ (excluding generated docs/reference/)
    • description in pyproject.toml and zensical.toml
    • inventories in zensical.toml if needed
  • DO NOT EDIT:
    • generated reference pages under docs/reference/
  • Existing docs, docstrings, tests, examples may be rough, missing, incomplete or misleading, it only serves as weak hint.
  • Favor bold, comprehensive rewrites over minor or incremental edits.
  • Keep docs concise, fluent, example-first.
  • Source code is the source of truth.
  • Use Google style docstrings. Read google-style.md for details.
  • Prefer Examples: sections with compact doctests for public APIs when the example is deterministic, useful, and runnable.
  • Treat doctests as executable tests, not decorative snippets; keep fixture-heavy, parametrized, or unstable behavior in tests/.
  • Use markdown in docstrings:
    • Use single backticks for inline code, NOT double backticks.
    • Cross-references are written as Markdown reference-style links: [Object 1][full.path.object1].

Suggested Layout

docs/
  README.md
  getting-started/
    ...
  guides/
    ...
  concepts/
    ...
  reference/  # generated, DO NOT EDIT
    package/
      README.md
      submodule.md
  advanced/
    ...
  • Keep only the sections the project needs.
  • Keep navigation shallow.

mkdocstrings Notes

  • The project uses zensical with mkdocstrings.
  • The __init__ method is merged into the class' signature and docstring.
  • The first line in __init__ methods' docstrings is ignored.

Validation

  • Run rumdl fmt .. Treat its findings as weak hints, not strong constraints.
  • Run uv run pytest ... for changed doctests.
  • Run mise run lint.
  • Run mise run docs:build.
  • If validation fails for unrelated reasons, separate those failures from the docs change and report them clearly.

Comments

Markdown supported