{"id":"e3fab05c-49bc-4868-bb9f-3d066f8d61cc","shortId":"w3w2N6","kind":"skill","title":"sphinx","tagline":"Use when editing Sphinx docs, conf.py, .rst files, docs/source, autodoc, Read the Docs builds, Shibuya or Immaterial themes, Wasm extensions, VHS terminal recordings, or Sphinx CI.","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-05-18T19:07:39.539Z","embedding":null,"createdAt":"2026-04-23T13:04:01.705Z","updatedAt":"2026-05-18T19:07:39.539Z","lastSeenAt":"2026-05-18T19:07:39.539Z","tsv":"'/../examples/demo.py':165 '/3':98,591 '/cofin/flow/blob/main/templates/styleguides/general.md)':721 '/cofin/flow/blob/main/templates/styleguides/languages/python.md)':725 '/en/20/':103 '/index':608 '1':237 '2':274,604 '2025':48 '3':295 '4':330 '5':360 '8.0':397 '9':398 'acm':566,595,598 'acme.client.acmeclient':624 'acme.core':615 'action':366,689 'add':363 'admonit':180 'ahead':188 'alphabet':199 'api':268,612 'api/index':609 'appear':464 'author':51 'autobuild':353,356 'autoclass':142,623 'autodoc':11,76,77,81,84,131,189,191,200,278,456,532,562,579,583 'automodul':133,614 'b':340 'baselin':703 'bash':334 'block':150,153 'break':404 'broken':446 'build':15,331,336,339,369,376,432,438,527,548,692 'bysourc':80,194,582 'card':325 'case':736 'catch':445 'chang':405 'checkpoint':503 'choos':64 'ci':27,434,444,546 'ci/cd':361,685 'class':85,425 'code':149,152,318,488 'code-block':151 'complet':529 'concept':312,469 'conf.py':7,41,246,261,557 'configur':190,275,507,520,650,659 'content':234,297,483 'copybutton':60,573 'copyright':47 'correct':545 'creat':679 'cross':90,119,414,539 'cross-project':89,413 'cross-refer':118,538 'danger':186 'def':155 'deliv':505 'demo':665 'deploy':381,694 'descript':83,202,208,458,585 'design':62,322,575,654 'detail':633,739 'direct':132 'directori':244,250 'doc':6,14,125,227,243,260,342,357,370,422,426,467,542,549 'docs.python.org':97,590 'docs.python.org/3':96,589 'docs.sqlalchemy.org':102 'docs.sqlalchemy.org/en/20/':101 'docs/_build/html':343,358 'docs/api/index.rst':610 'docs/conf.py':44,563 'docs/index.rst':593 'docs/source':10 'docstr':221 'document':37,600,644,695 'duplic':233,713 'edg':735 'edit':4 'embed':681 'enabl':213,277 'end':175,178,499 'end-befor':174,498 'end-exampl':177 'error':442,453 'etc':231 'everi':372 'exampl':173,179,319,490,554 'expand':35 'expert':30 'extens':21,54,212,276,286,290,407,511,567,639,664 'extern':225,421,523 'fail':374,551 'faster':484 'file':9,161 'find':482 'flag':380 'focus':476,729 'follow':643 'func':129,424,543 'general':717 'generic':708 'get':264,606 'getting-start':263,605 'github':365,383,688 'github.com':720,724 'github.com/cofin/flow/blob/main/templates/styleguides/general.md)':719 'github.com/cofin/flow/blob/main/templates/styleguides/languages/python.md)':723 'go':347 'googl':215 'google-styl':214 'grid':323 'guardrail':391 'guid':300,474,634 'guidelin':677 'hardcod':418 'head':112 'hello':156 'hidden':253,602 'hierarchi':113 'hint':205 'html':66,72,341,576 'hub':328 'immateri':18,71,647 'import':182 'includ':159 'index':631 'index.rst':247,256,262,266,269 'info':463 'inform':183 'infrastructur':684 'inherit':141,622 'init':148,629 'inlin':487 'installation.rst':267 'integr':362,669,738 'interact':670 'intersphinx':88,93,222,279,411,429,517,586 'keep':306,346,459,489,726 'keep-go':345 'key':105 'knowledg':31 'label':123 'label-nam':122 'languag':166 'language/framework':709 'link':92,223,416,478 'literalinclud':164,314,485 'local':335 'long':299,473 'main':390 'maintain':33 'map':94,430,518,587 'marker':163,316,501 'materi':653 'maxdepth':603 'member':78,135,138,144,147,192,580,616,619,625,628 'merg':388,455 'minim':556 'miss':448 'mode':349 'modul':449 'modules.rst':270 'modules/classes':537 'mymodule.myfunction':130 'mypackage.module':134 'mypackage.myclass':143 'myproject':46 'name':124 'napoleon':211,280 'navig':258,327 'never':417 'none':99,104,592 'note':181 'numpi':219 'numpy-styl':218 'offici':696 'one':65,311,468 'oper':187 'order':79,193,197,581 'org':50,53 'other-pag':126 'page':114,128,305,308,384,471,477,560 'paramet':207,466 'path':74 'pattern':107 'per':303,470 'per-top':302 'pick':533 'pin':287,392,406,514 'pipelin':686 'playground':667,672 'pr':373 'prefer':320 'preserv':195 'prevent':402 'principl':718 'print':157 'project':45,91,226,238,415,565 'public':536 'put':203 'pyproject.toml':293,400,516 'python':43,95,154,167,228,564,588,722 'quick':39 'read':12 'readabl':461 'reader':481 'readthedoc':386 'record':24,675,683 'reduc':712 'ref':121,541 'refer':40,120,447,524,540,613,630,640,697 'references/ci-cd.md':687 'references/immaterial-theme.md':649 'references/shibuya.md':658 'references/vhs-demos.md':676 'references/wasm-playground.md':668 'resolv':544 'role':427 'rst':8,106,108,451,559,594,611 'rule':710 'run':435 'runnabl':491 'scope':309 'section':111,116,249 'separ':87 'set':240 'setup':42 'share':701,705 'shibuya':16,68,578,656,662 'shibuya.lepture.com':700 'show':140,621 'show-inherit':139,620 'signatur':86,210,460 'skill':29,716,728 'skill-sphinx' 'sourc':196 'source-cofin' 'special':146,627 'special-memb':145,626 'specif':285,636,733 'specifi':395 'sphinx':1,5,26,28,36,59,61,70,288,321,338,352,355,393,396,437,506,509,526,572,574,646 'sphinx-autobuild':351,354 'sphinx-build':337,436,525 'sphinx-immaterial.readthedocs.io':699 'sphinx.ext.autodoc':55,568 'sphinx.ext.intersphinx':56,569 'sphinx.ext.napoleon':57,570 'sphinx.ext.viewcode':58,571 'split':298,472 'sqlalchemi':100,230 'start':169,172,265,496,607 'start-aft':168,495 'start-exampl':171 'static':73,75,271 'stdlib':229 'step':236,273,294,329,359 'structur':239 'style':216,220 'styleguid':702,706 'subsect':117 'surpris':403 'syntax':452 'task':555 'templat':272 'termin':23,674 'test':333,431 'testabl':493 'text':259 'theme':19,63,67,284,577,637,645,648,655,657,663 'theme-specif':283 'titl':109,115 'toctre':254,480,601 'tool':732 'tool-specif':731 'topic':304 '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':204,462 'typehint':82,201,457,584 'undoc':137,618 'undoc-memb':136,617 'url':419 'use':2,251,313,410,423,494,704 'valid':502 'verifi':508 'version':291,394,408,512 'vhs':22,673,682 'via':479 'viewcod':281 'w':344,379,439,528 'warn':185,378,440,531,553 'wasm':20,666,671 'watch':348 'welcom':596 'without':232,530 'workflow':235,367,547,690,734 'workspac':38 'world':158 'write':296 'www.sphinx-doc.org':698","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-05-18T19:07:39.539Z"}],"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-27T19:07:26Z","description":"Context-Driven Development toolkit for AI agents — spec-first planning, TDD workflow, and Beads integration.","skill_md_sha":"32edafba232c531f99fe861d95b1e6f0104d8f88","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":"Use when editing Sphinx docs, conf.py, .rst files, docs/source, autodoc, Read the Docs builds, Shibuya or Immaterial themes, Wasm extensions, VHS terminal recordings, or Sphinx CI."},"skills_sh_url":"https://skills.sh/cofin/flow/sphinx"},"updatedAt":"2026-05-18T19:07:39.539Z"}}