MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-write-doc
pywf-oss-write-doc
VerifiedWrite 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
- Pick the channel, the format, and the place.
- Check the fact belongs in user docs (
18-knowledge-channels.mdsection 2). How to maintain this repo goes topywf-oss-write-maintain-skill; say so, and stop. - A notebook for runnable usage guides,
.rstfor concepts and design notes. If the user did not say, choose, and state the choice. - List the existing page folders, then choose the
NN-Titlefolder that puts the page at the right sidebar position.
- Check the fact belongs in user docs (
- Gather facts from
api.pyand the docstrings of what you document. Examples import from<package_name>.api, as users would. - 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
NotebookEditornbformat.
- Run notebooks with the
nbconvertcommand in17-nbsphinx.mdsection 5. Every cell must succeed; the outputs are committed. - Build and check as in
13-sphinx.mdsection 4: no new warnings, 0 unresolved cross-references (check_doc_xrefs.py,13-sphinx.mdsection 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.rstshort; long material goes in a docs page the README links to.
Next step: pywf-oss-changelog.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 117k | Updated | Claude CodeCodex | Verified | Install |
| 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: 117k | Updated | Claude CodeCodex | Verified | Install |