Skip to content

MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-write-doc

pywf-oss-write-doc

Verified

Write or update a user-facing Sphinx documentation page of a pywf open-source Python library, as reStructuredText or as a Jupyter notebook with raw reStructuredText cells for cross-references, then build and check it. Use when the user asks to document a feature for its users, write a guide or tutorial page, add a notebook example, or fix the docs. Maintainer knowledge goes to pywf-oss-write-maintain-skill instead.

Write or update one docs page under docs/source/ that builds cleanly, appears in the sidebar, and links correctly to the API reference and other pages.

Read ../pywf-oss-base/SKILL.md, then:

  • ../pywf-oss-base/references/13-sphinx.md
  • ../pywf-oss-base/references/14-docfly.md
  • ../pywf-oss-base/references/15-furo.md (only when changing the look or the theme)
  • ../pywf-oss-base/references/16-sphinx-design.md (only when the page needs layout or widgets: cards, tabs, dropdowns, badges, buttons)
  • ../pywf-oss-base/references/17-nbsphinx.md (only for notebook pages)
  • ../pywf-oss-base/references/18-knowledge-channels.md

Templates: ../pywf-oss-base/assets/notebook-page-template.ipynb and ../pywf-oss-base/assets/raw-rst-cell.json.

Steps

  1. Pick the channel, the format, and the place.
    • Check the fact belongs in user docs (18-knowledge-channels.md section 2). How to maintain this repo goes to pywf-oss-write-maintain-skill; say so, and stop.
    • A notebook for runnable usage guides, .rst for concepts and design notes. If the user did not say, choose, and state the choice.
    • List the existing page folders, then choose the NN-Title folder that puts the page at the right sidebar position.
  2. Gather facts from api.py and the docstrings of what you document. Examples import from <package_name>.api, as users would.
  3. Write.
    • Give the page a unique label and a title (in a notebook, both in a raw reStructuredText cell).
    • Use cross-reference roles for API names, and :ref: for other pages.
    • Edit notebooks with NotebookEdit or nbformat.
  4. Run notebooks with the nbconvert command in 17-nbsphinx.md section 5. Every cell must succeed; the outputs are committed.
  5. Build and check as in 13-sphinx.md section 4: no new warnings, 0 unresolved cross-references (check_doc_xrefs.py, 13-sphinx.md section 2.2), and the page in the sidebar with the right title. For layout work, also run the visual check.

Boundaries

  • Never edit docs/source/api/. To improve the API pages, improve the docstrings, and say so.
  • Keep README.rst short; long material goes in a docs page the README links to.

Next step: pywf-oss-changelog.

deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall