{"id":"e3fab05c-49bc-4868-bb9f-3d066f8d61cc","shortId":"w3w2N6","kind":"skill","title":"sphinx","tagline":"Auto-activate for conf.py (Sphinx), .rst files, docs/source/. Produces Sphinx documentation sites with RST, autodoc, themes (Shibuya/Immaterial), and CI/CD integration. Use when: editing conf.py, reStructuredText (.rst), autodoc, readthedocs builds, Shibuya theme, Wasm extensions","description":"# Sphinx Skill\n\nExpert knowledge for maintaining and expanding Sphinx documentation workspaces.\n\n## Quick Reference\n\n### conf.py Setup\n\n```python\n# docs/conf.py\nproject = \"MyProject\"\ncopyright = \"2025, My Org\"\nauthor = \"My Org\"\n\nextensions = [\n    \"sphinx.ext.autodoc\",\n    \"sphinx.ext.intersphinx\",\n    \"sphinx.ext.napoleon\",\n    \"sphinx.ext.viewcode\",\n    \"sphinx_copybutton\",\n    \"sphinx_design\",\n]\n\n# Theme (choose one)\nhtml_theme = \"shibuya\"  # or \"sphinx_immaterial\"\nhtml_static_path = [\"_static\"]\n\n# Autodoc\nautodoc_member_order = \"bysource\"\nautodoc_typehints = \"description\"\nautodoc_class_signature = \"separated\"\n\n# Intersphinx (cross-project links)\nintersphinx_mapping = {\n    \"python\": (\"https://docs.python.org/3\", None),\n    \"sqlalchemy\": (\"https://docs.sqlalchemy.org/en/20/\", None),\n}\n```\n\n### Key RST Patterns\n\n```rst\n.. Title and sections (heading hierarchy)\n==========\nPage Title\n==========\n\nSection\n-------\n\nSubsection\n^^^^^^^^^^\n\n.. Cross-references\n:ref:`label-name`\n:doc:`other-page`\n:func:`mymodule.myfunction`\n\n.. Autodoc directives\n.. automodule:: mypackage.module\n   :members:\n   :undoc-members:\n   :show-inheritance:\n\n.. autoclass:: mypackage.MyClass\n   :members:\n   :special-members: __init__\n\n.. Code blocks\n.. code-block:: python\n\n   def hello():\n       print(\"world\")\n\n.. Include from file with markers\n.. literalinclude:: ../../examples/demo.py\n   :language: python\n   :start-after: # start-example\n   :end-before: # end-example\n\n.. Admonitions\n.. note::\n   Important information here.\n\n.. warning::\n   Dangerous operation ahead.\n```\n\n### Autodoc Configuration\n\n- `autodoc_member_order = \"bysource\"` -- preserves source order (not alphabetical).\n- `autodoc_typehints = \"description\"` -- puts type hints in parameter descriptions, not signatures.\n- `napoleon` extension -- enables Google-style and NumPy-style docstrings.\n- `intersphinx` -- links to external project docs (Python stdlib, SQLAlchemy, etc.) without duplicating content.\n\n<workflow>\n\n## Workflow\n\n### Step 1: Project Structure\n\nSet up the docs directory with `conf.py`, `index.rst`, and section directories. Use a hidden toctree in `index.rst` for navigation.\n\n```text\ndocs/\n├── conf.py\n├── index.rst\n├── getting-started/\n│   ├── index.rst\n│   └── installation.rst\n├── api/\n│   ├── index.rst\n│   └── modules.rst\n├── _static/\n└── _templates/\n```\n\n### Step 2: Configure Extensions\n\nEnable `autodoc`, `intersphinx`, `napoleon`, `viewcode`, and theme-specific extensions. Pin Sphinx and extension versions in `pyproject.toml`.\n\n### Step 3: Write Content\n\nSplit long guides into per-topic pages. Keep each page scoped to one concept. Use `literalinclude` with markers for code examples. Prefer `sphinx_design` grids and cards for navigation hubs.\n\n### Step 4: Build and Test\n\n```bash\n# Local build\nsphinx-build -b html docs/ docs/_build/html -W --keep-going\n\n# Watch mode (with sphinx-autobuild)\nsphinx-autobuild docs/ docs/_build/html\n```\n\n### Step 5: CI/CD Integration\n\nAdd a GitHub Actions workflow that builds docs on every PR. Fail the build on warnings (`-W` flag). Deploy to GitHub Pages or ReadTheDocs on merge to main.\n\n</workflow>\n\n<guardrails>\n\n## Guardrails\n\n- **Pin Sphinx version** -- specify `sphinx>=8.0,<9` in `pyproject.toml` to prevent surprise breaking changes. Pin extension versions too.\n- **Use intersphinx for cross-project links** -- never hardcode URLs to external docs. Use `:func:`, `:class:`, `:doc:` roles with intersphinx mappings.\n- **Test builds in CI** -- run `sphinx-build -W` (warnings as errors) in CI. Catch broken references, missing modules, and RST syntax errors before merge.\n- **`autodoc_typehints = \"description\"`** -- keeps signatures readable; type info appears in parameter docs.\n- **One concept per page** -- split long guides into focused pages linked via toctree. Readers find content faster.\n- **`literalinclude` over inline code** -- keeps examples runnable and testable. Use `start-after`/`end-before` markers.\n\n</guardrails>\n\n<validation>\n\n### Validation Checkpoint\n\nBefore delivering Sphinx configurations, verify:\n\n- [ ] Sphinx and extension versions are pinned in pyproject.toml\n- [ ] `intersphinx_mapping` is configured for all external references\n- [ ] `sphinx-build -W` completes without warnings\n- [ ] Autodoc picks up all public modules/classes\n- [ ] Cross-references (`:ref:`, `:doc:`, `:func:`) resolve correctly\n- [ ] CI workflow builds docs and fails on warnings\n\n</validation>\n\n<example>\n\n## Example\n\n**Task:** Minimal conf.py and RST page with autodoc.\n\n**`docs/conf.py`:**\n\n```python\nproject = \"Acme\"\nextensions = [\n    \"sphinx.ext.autodoc\",\n    \"sphinx.ext.intersphinx\",\n    \"sphinx.ext.napoleon\",\n    \"sphinx.ext.viewcode\",\n    \"sphinx_copybutton\",\n    \"sphinx_design\",\n]\n\nhtml_theme = \"shibuya\"\n\nautodoc_member_order = \"bysource\"\nautodoc_typehints = \"description\"\n\nintersphinx_mapping = {\n    \"python\": (\"https://docs.python.org/3\", None),\n}\n```\n\n**`docs/index.rst`:**\n\n```rst\n=====\nAcme\n=====\n\nWelcome to Acme's documentation.\n\n.. toctree::\n   :hidden:\n   :maxdepth: 2\n\n   getting-started/index\n   api/index\n```\n\n**`docs/api/index.rst`:**\n\n```rst\n=============\nAPI Reference\n=============\n\n.. automodule:: acme.core\n   :members:\n   :undoc-members:\n   :show-inheritance:\n\n.. autoclass:: acme.client.AcmeClient\n   :members:\n   :special-members: __init__\n```\n\n</example>\n\n---\n\n## References Index\n\nFor detailed guides on specific themes and extensions, refer to the following documents:\n\n### Themes\n\n- **[Sphinx Immaterial Theme](references/immaterial-theme.md)** -- Configuration for the Material Design theme.\n- **[Shibuya Theme](references/shibuya.md)** -- Configuration for the Shibuya theme.\n\n### Extensions & Demos\n\n- **[Wasm Playground](references/wasm-playground.md)** -- Integrating interactive Wasm playgrounds.\n- **[VHS Terminal Recordings](references/vhs-demos.md)** -- Guidelines for creating and embedding VHS recordings.\n\n### Infrastructure\n\n- **[CI/CD Pipelines](references/ci-cd.md)** -- GitHub Actions workflows for building and deploying documentation.\n\n---\n\n## Official References\n\n- <https://www.sphinx-doc.org/>\n- <https://sphinx-immaterial.readthedocs.io/>\n- <https://shibuya.lepture.com/>\n\n## Shared Styleguide Baseline\n\n- Use shared styleguides for generic language/framework rules to reduce duplication in this skill.\n- [General Principles](https://github.com/cofin/flow/blob/main/templates/styleguides/general.md)\n- [Python](https://github.com/cofin/flow/blob/main/templates/styleguides/languages/python.md)\n- Keep this skill focused on tool-specific workflows, edge cases, and integration details.","tags":["sphinx","flow","cofin","agent-skills","ai-agents","beads","claude-code","codex","cursor","developer-tools","gemini-cli","opencode"],"capabilities":["skill","source-cofin","skill-sphinx","topic-agent-skills","topic-ai-agents","topic-beads","topic-claude-code","topic-codex","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-opencode","topic-plugin","topic-slash-commands","topic-spec-driven-development"],"categories":["flow"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/cofin/flow/sphinx","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add cofin/flow","source_repo":"https://github.com/cofin/flow","install_from":"skills.sh"}},"qualityScore":"0.455","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 11 github stars · SKILL.md body (6,584 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-24T07:03:20.065Z","embedding":null,"createdAt":"2026-04-23T13:04:01.705Z","updatedAt":"2026-04-24T07:03:20.065Z","lastSeenAt":"2026-04-24T07:03:20.065Z","tsv":"'/../examples/demo.py':173 '/3':106,599 '/cofin/flow/blob/main/templates/styleguides/general.md)':729 '/cofin/flow/blob/main/templates/styleguides/languages/python.md)':733 '/en/20/':111 '/index':616 '1':245 '2':282,612 '2025':56 '3':303 '4':338 '5':368 '8.0':405 '9':406 'acm':574,603,606 'acme.client.acmeclient':632 'acme.core':623 'action':374,697 'activ':4 'add':371 'admonit':188 'ahead':196 'alphabet':207 'api':276,620 'api/index':617 'appear':472 'author':59 'auto':3 'auto-activ':2 'autobuild':361,364 'autoclass':150,631 'autodoc':17,29,84,85,89,92,139,197,199,208,286,464,540,570,587,591 'automodul':141,622 'b':348 'baselin':711 'bash':342 'block':158,161 'break':412 'broken':454 'build':31,339,344,347,377,384,440,446,535,556,700 'bysourc':88,202,590 'card':333 'case':744 'catch':453 'chang':413 'checkpoint':511 'choos':72 'ci':442,452,554 'ci/cd':21,369,693 'class':93,433 'code':157,160,326,496 'code-block':159 'complet':537 'concept':320,477 'conf.py':6,26,49,254,269,565 'configur':198,283,515,528,658,667 'content':242,305,491 'copybutton':68,581 'copyright':55 'correct':553 'creat':687 'cross':98,127,422,547 'cross-project':97,421 'cross-refer':126,546 'danger':194 'def':163 'deliv':513 'demo':673 'deploy':389,702 'descript':91,210,216,466,593 'design':70,330,583,662 'detail':641,747 'direct':140 'directori':252,258 'doc':133,235,251,268,350,365,378,430,434,475,550,557 'docs.python.org':105,598 'docs.python.org/3':104,597 'docs.sqlalchemy.org':110 'docs.sqlalchemy.org/en/20/':109 'docs/_build/html':351,366 'docs/api/index.rst':618 'docs/conf.py':52,571 'docs/index.rst':601 'docs/source':10 'docstr':229 'document':13,45,608,652,703 'duplic':241,721 'edg':743 'edit':25 'embed':689 'enabl':221,285 'end':183,186,507 'end-befor':182,506 'end-exampl':185 'error':450,461 'etc':239 'everi':380 'exampl':181,187,327,498,562 'expand':43 'expert':38 'extens':35,62,220,284,294,298,415,519,575,647,672 'extern':233,429,531 'fail':382,559 'faster':492 'file':9,169 'find':490 'flag':388 'focus':484,737 'follow':651 'func':137,432,551 'general':725 'generic':716 'get':272,614 'getting-start':271,613 'github':373,391,696 'github.com':728,732 'github.com/cofin/flow/blob/main/templates/styleguides/general.md)':727 'github.com/cofin/flow/blob/main/templates/styleguides/languages/python.md)':731 'go':355 'googl':223 'google-styl':222 'grid':331 'guardrail':399 'guid':308,482,642 'guidelin':685 'hardcod':426 'head':120 'hello':164 'hidden':261,610 'hierarchi':121 'hint':213 'html':74,80,349,584 'hub':336 'immateri':79,655 'import':190 'includ':167 'index':639 'index.rst':255,264,270,274,277 'info':471 'inform':191 'infrastructur':692 'inherit':149,630 'init':156,637 'inlin':495 'installation.rst':275 'integr':22,370,677,746 'interact':678 'intersphinx':96,101,230,287,419,437,525,594 'keep':314,354,467,497,734 'keep-go':353 'key':113 'knowledg':39 'label':131 'label-nam':130 'languag':174 'language/framework':717 'link':100,231,424,486 'literalinclud':172,322,493 'local':343 'long':307,481 'main':398 'maintain':41 'map':102,438,526,595 'marker':171,324,509 'materi':661 'maxdepth':611 'member':86,143,146,152,155,200,588,624,627,633,636 'merg':396,463 'minim':564 'miss':456 'mode':357 'modul':457 'modules.rst':278 'modules/classes':545 'mymodule.myfunction':138 'mypackage.module':142 'mypackage.myclass':151 'myproject':54 'name':132 'napoleon':219,288 'navig':266,335 'never':425 'none':107,112,600 'note':189 'numpi':227 'numpy-styl':226 'offici':704 'one':73,319,476 'oper':195 'order':87,201,205,589 'org':58,61 'other-pag':134 'page':122,136,313,316,392,479,485,568 'paramet':215,474 'path':82 'pattern':115 'per':311,478 'per-top':310 'pick':541 'pin':295,400,414,522 'pipelin':694 'playground':675,680 'pr':381 'prefer':328 'preserv':203 'prevent':410 'principl':726 'print':165 'produc':11 'project':53,99,234,246,423,573 'public':544 'put':211 'pyproject.toml':301,408,524 'python':51,103,162,175,236,572,596,730 'quick':47 'readabl':469 'reader':489 'readthedoc':30,394 'record':683,691 'reduc':720 'ref':129,549 'refer':48,128,455,532,548,621,638,648,705 'references/ci-cd.md':695 'references/immaterial-theme.md':657 'references/shibuya.md':666 'references/vhs-demos.md':684 'references/wasm-playground.md':676 'resolv':552 'restructuredtext':27 'role':435 'rst':8,16,28,114,116,459,567,602,619 'rule':718 'run':443 'runnabl':499 'scope':317 'section':119,124,257 'separ':95 'set':248 'setup':50 'share':709,713 'shibuya':32,76,586,664,670 'shibuya.lepture.com':708 'shibuya/immaterial':19 'show':148,629 'show-inherit':147,628 'signatur':94,218,468 'site':14 'skill':37,724,736 'skill-sphinx' 'sourc':204 'source-cofin' 'special':154,635 'special-memb':153,634 'specif':293,644,741 'specifi':403 'sphinx':1,7,12,36,44,67,69,78,296,329,346,360,363,401,404,445,514,517,534,580,582,654 'sphinx-autobuild':359,362 'sphinx-build':345,444,533 'sphinx-immaterial.readthedocs.io':707 'sphinx.ext.autodoc':63,576 'sphinx.ext.intersphinx':64,577 'sphinx.ext.napoleon':65,578 'sphinx.ext.viewcode':66,579 'split':306,480 'sqlalchemi':108,238 'start':177,180,273,504,615 'start-aft':176,503 'start-exampl':179 'static':81,83,279 'stdlib':237 'step':244,281,302,337,367 'structur':247 'style':224,228 'styleguid':710,714 'subsect':125 'surpris':411 'syntax':460 'task':563 'templat':280 'termin':682 'test':341,439 'testabl':501 'text':267 'theme':18,33,71,75,292,585,645,653,656,663,665,671 'theme-specif':291 'titl':117,123 'toctre':262,488,609 'tool':740 'tool-specif':739 'topic':312 'topic-agent-skills' 'topic-ai-agents' 'topic-beads' 'topic-claude-code' 'topic-codex' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-opencode' 'topic-plugin' 'topic-slash-commands' 'topic-spec-driven-development' 'type':212,470 'typehint':90,209,465,592 'undoc':145,626 'undoc-memb':144,625 'url':427 'use':23,259,321,418,431,502,712 'valid':510 'verifi':516 'version':299,402,416,520 'vhs':681,690 'via':487 'viewcod':289 'w':352,387,447,536 'warn':193,386,448,539,561 'wasm':34,674,679 'watch':356 'welcom':604 'without':240,538 'workflow':243,375,555,698,742 'workspac':46 'world':166 'write':304 'www.sphinx-doc.org':706","prices":[{"id":"a8af9404-9ca7-46e2-b2c5-c871d1b83f09","listingId":"e3fab05c-49bc-4868-bb9f-3d066f8d61cc","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"cofin","category":"flow","install_from":"skills.sh"},"createdAt":"2026-04-23T13:04:01.705Z"}],"sources":[{"listingId":"e3fab05c-49bc-4868-bb9f-3d066f8d61cc","source":"github","sourceId":"cofin/flow/sphinx","sourceUrl":"https://github.com/cofin/flow/tree/main/skills/sphinx","isPrimary":false,"firstSeenAt":"2026-04-23T13:04:01.705Z","lastSeenAt":"2026-04-24T07:03:20.065Z"}],"details":{"listingId":"e3fab05c-49bc-4868-bb9f-3d066f8d61cc","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"cofin","slug":"sphinx","github":{"repo":"cofin/flow","stars":11,"topics":["agent-skills","ai-agents","beads","claude-code","codex","context-driven-development","cursor","developer-tools","gemini-cli","opencode","plugin","slash-commands","spec-driven-development","subagents","tdd","workflow"],"license":"apache-2.0","html_url":"https://github.com/cofin/flow","pushed_at":"2026-04-19T23:22:27Z","description":"Context-Driven Development toolkit for AI agents — spec-first planning, TDD workflow, and Beads integration.","skill_md_sha":"4598c2e7a48ee083d207d9c2b054e8aa3ce16083","skill_md_path":"skills/sphinx/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/cofin/flow/tree/main/skills/sphinx"},"layout":"multi","source":"github","category":"flow","frontmatter":{"name":"sphinx","description":"Auto-activate for conf.py (Sphinx), .rst files, docs/source/. Produces Sphinx documentation sites with RST, autodoc, themes (Shibuya/Immaterial), and CI/CD integration. Use when: editing conf.py, reStructuredText (.rst), autodoc, readthedocs builds, Shibuya theme, Wasm extensions, VHS terminal recordings, or any Sphinx project setup. Not for MkDocs, Docusaurus, or Mintlify documentation sites."},"skills_sh_url":"https://skills.sh/cofin/flow/sphinx"},"updatedAt":"2026-04-24T07:03:20.065Z"}}