skills.rest
jcg-admin
jcg-adminCOMMUNITY
Explore all skills by this author →
GitHub

sphinx

Builds multi-format documentation from reStructuredText and Markdown sources using Sphinx.

Updated Mar 14, 2026
Search Tags:#pdf#documentation#markdown#python#sphinx#restructuredtext#autodoc
One-click install
npx skills add https://github.com/jcg-admin/IACT-ui --skill sphinx-jcg-admin
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sphinx
Source: https://github.com/jcg-admin/IACT-ui/tree/main/.claude/skills/sphinx
Command: npx skills add https://github.com/jcg-admin/IACT-ui --skill sphinx-jcg-admin

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Creating and maintaining professional project documentation is time-consuming, especially when you need multiple output formats (HTML, PDF, ePub), API references generated from docstrings, and consistent cross-referencing. This Skill guides the full Sphinx workflow from project scaffolding to troubleshooting broken builds. ## Core Features & Use Cases - Project Scaffolding & Builds: Initialize projects with sphinx-quickstart, configure conf.py, and build HTML, PDF, and ePub outputs via make targets. - API Documentation with Autodoc: Generate Python API references directly from docstrings using sphinx.ext.autodoc, with Markdown support via myst_parser. - Extension & Theme Configuration: Configure extensions (intersphinx, PlantUML, viewcode), custom directives, and themes like pydata_sphinx_theme or sphinx_rtd_theme. - Troubleshooting: Resolve common failures such as unknown directives, broken cross-references, slow builds, and LaTeX/PDF errors. - Use Case: You have a Python package with docstrings but no docs site. Use this Skill to scaffold a Sphinx project, enable autodoc and Markdown support, apply a theme, and produce both HTML and PDF documentation. ## Quick Start Ask the assistant to set up a new Sphinx documentation project with autodoc enabled and build the HTML output.

Frequently Asked Questions about sphinx

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create documentation for a Python project with Sphinx?▼

Run sphinx-quickstart to scaffold the project, then enable sphinx.ext.autodoc in conf.py and use automodule directives in your RST files to generate API docs from docstrings. Build with make html.

How to build Sphinx documentation as both HTML and PDF?▼

Run make html for HTML output. For PDF, install a LaTeX distribution such as texlive-latex-full, then run make latexpdf; the PDF is generated in the build/latex directory.

Does Sphinx support Markdown files?▼

Yes, install the myst_parser package and add it to the extensions list in conf.py. Then map the .md suffix in source_suffix so Sphinx parses Markdown alongside reStructuredText.

Why does my Sphinx build fail with an unknown directive error?▼

The directive's extension is missing or not loaded. Check that the extension is listed in conf.py, verify it imports correctly, and run make clean html to clear cached state.

How do I fix broken cross-references in Sphinx?▼

Ensure the target label exists and is defined with the .. _label: syntax before the section heading. Reference it with :ref:`label` and rebuild with make clean html to resolve stale references.

Why is autodoc not finding my Python module?▼

The module is not on the Python path during the build. Add the source directory to sys.path in conf.py, for example by inserting the project's src folder path before the autodoc directives run.

Related Skills

Explore More Software Engineering Skills→
fernando-fernandez3fernando-fernandez3

docs

Generate Markdown or reStructuredText documentation from codebases.

Community
Intermediate
DJ2695DJ2695

flutter-app-release

Automates end-to-end Flutter release pipelines for iOS, Android and Web hosting.

Community
Advanced
klhklh
9

code-documenter

Generate and validate docstrings, JSDoc, and OpenAPI specs for Python, TypeScript, and Node.js projects.

Community
Advanced
bryonjacobbryonjacob

documenting-with-mkdocs

Automate MkDocs Material documentation workflows for Python and JavaScript projects.

Community
Intermediate