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.
From flownpx claudepluginhub cofin/flow --plugin flowThis skill uses the workspace's default tool permissions.
references/ci-cd.mdreferences/immaterial-theme.mdreferences/shibuya.mdreferences/vhs-demos.mdreferences/wasm-playground.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Expert knowledge for maintaining and expanding Sphinx documentation workspaces.
# docs/conf.py
project = "MyProject"
copyright = "2025, My Org"
author = "My Org"
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinx_copybutton",
"sphinx_design",
]
# Theme (choose one)
html_theme = "shibuya" # or "sphinx_immaterial"
html_static_path = ["_static"]
# Autodoc
autodoc_member_order = "bysource"
autodoc_typehints = "description"
autodoc_class_signature = "separated"
# Intersphinx (cross-project links)
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
"sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
}
.. Title and sections (heading hierarchy)
==========
Page Title
==========
Section
-------
Subsection
^^^^^^^^^^
.. Cross-references
:ref:`label-name`
:doc:`other-page`
:func:`mymodule.myfunction`
.. Autodoc directives
.. automodule:: mypackage.module
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: mypackage.MyClass
:members:
:special-members: __init__
.. Code blocks
.. code-block:: python
def hello():
print("world")
.. Include from file with markers
.. literalinclude:: ../../examples/demo.py
:language: python
:start-after: # start-example
:end-before: # end-example
.. Admonitions
.. note::
Important information here.
.. warning::
Dangerous operation ahead.
autodoc_member_order = "bysource" -- preserves source order (not alphabetical).autodoc_typehints = "description" -- puts type hints in parameter descriptions, not signatures.napoleon extension -- enables Google-style and NumPy-style docstrings.intersphinx -- links to external project docs (Python stdlib, SQLAlchemy, etc.) without duplicating content.Set up the docs directory with conf.py, index.rst, and section directories. Use a hidden toctree in index.rst for navigation.
docs/
├── conf.py
├── index.rst
├── getting-started/
│ ├── index.rst
│ └── installation.rst
├── api/
│ ├── index.rst
│ └── modules.rst
├── _static/
└── _templates/
Enable autodoc, intersphinx, napoleon, viewcode, and theme-specific extensions. Pin Sphinx and extension versions in pyproject.toml.
Split 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.
# Local build
sphinx-build -b html docs/ docs/_build/html -W --keep-going
# Watch mode (with sphinx-autobuild)
sphinx-autobuild docs/ docs/_build/html
Add 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.
sphinx>=8.0,<9 in pyproject.toml to prevent surprise breaking changes. Pin extension versions too.:func:, :class:, :doc: roles with intersphinx mappings.sphinx-build -W (warnings as errors) in CI. Catch broken references, missing modules, and RST syntax errors before merge.autodoc_typehints = "description" -- keeps signatures readable; type info appears in parameter docs.literalinclude over inline code -- keeps examples runnable and testable. Use start-after/end-before markers.Before delivering Sphinx configurations, verify:
intersphinx_mapping is configured for all external referencessphinx-build -W completes without warnings:ref:, :doc:, :func:) resolve correctlyTask: Minimal conf.py and RST page with autodoc.
docs/conf.py:
project = "Acme"
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinx_copybutton",
"sphinx_design",
]
html_theme = "shibuya"
autodoc_member_order = "bysource"
autodoc_typehints = "description"
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
}
docs/index.rst:
=====
Acme
=====
Welcome to Acme's documentation.
.. toctree::
:hidden:
:maxdepth: 2
getting-started/index
api/index
docs/api/index.rst:
=============
API Reference
=============
.. automodule:: acme.core
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: acme.client.AcmeClient
:members:
:special-members: __init__
</example>
For detailed guides on specific themes and extensions, refer to the following documents: