sphinx
SKILL.md
Sphinx Python Documentation Skill
Generate professional, comprehensive documentation for Python projects with Sphinx. This skill covers API documentation extraction, multiple output formats, and integration with Read the Docs.
When to Use This Skill
USE When
- Building Python library or package documentation
- Need automatic API reference from docstrings
- Require PDF or ePub documentation output
- Using Google or NumPy docstring styles
- Need cross-references between documentation projects
- Deploying to Read the Docs
- Building scientific or academic documentation
- Need versioned API documentation
- Working with large Python codebases
- Require internationalized documentation
DON'T USE When
- Simple project documentation without API docs (use MkDocs)
- Non-Python projects (use MkDocs or Docusaurus)
- Need React components in docs (use Docusaurus)
- Quick format conversion only (use Pandoc)
- Building presentation slides (use Marp)
- Collaborative wiki-style docs (use GitBook)
Prerequisites
Installation
# Core Sphinx installation
pip install sphinx
# With common extensions
pip install sphinx \
sphinx-rtd-theme \
sphinx-autodoc-typehints \
sphinx-copybutton \
myst-parser \
sphinxcontrib-mermaid
# Using uv
uv pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
# For PDF output
pip install sphinx latexmk
# Plus LaTeX distribution (texlive-full on Ubuntu, MacTeX on macOS)
# Verify installation
sphinx-build --version
System Requirements
- Python 3.8 or higher
- pip or uv package manager
- LaTeX distribution (for PDF output)
- Graphviz (optional, for diagrams)
Core Capabilities
1. Project Initialization
# Quick start with sphinx-quickstart
sphinx-quickstart docs
# Answer the prompts:
# > Separate source and build directories (y/n) [n]: y
# > Project name: MyProject
# > Author name(s): Your Name
# > Project release: 1.0.0
# > Project language [en]: en
# Generated structure:
# docs/
# ├── source/
# │ ├── conf.py
# │ ├── index.rst
# │ └── _static/
# │ └── _templates/
# └── build/
# └── (output files)
# Or manual setup
mkdir -p docs/source docs/build
touch docs/source/conf.py docs/source/index.rst
2. Basic Configuration (conf.py)
# docs/source/conf.py
# -- Project information -----------------------------------------------------
project = 'MyProject'
copyright = '2024-2026, Your Name'
author = 'Your Name'
release = '1.0.0'
version = '1.0'
# -- General configuration ---------------------------------------------------
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.githubpages',
'sphinx_rtd_theme',
'sphinx_copybutton',
'myst_parser',
]
# Source file suffixes
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
# Master document
master_doc = 'index'
# Exclude patterns
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# Pygments style
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_logo = '_static/logo.png'
html_favicon = '_static/favicon.ico'
html_theme_options = {
'logo_only': False,
'display_version': True,
'prev_next_buttons_location': 'bottom',
'style_external_links': True,
'style_nav_header_background': '#2980B9',
# Toc options
'collapse_navigation': False,
'sticky_navigation': True,
'navigation_depth': 4,
'includehidden': True,
'titles_only': False,
}
# -- Options for autodoc -----------------------------------------------------
autodoc_default_options = {
'members': True,
'member-order': 'bysource',
'special-members': '__init__',
'undoc-members': True,
'exclude-members': '__weakref__',
'show-inheritance': True,
}
autodoc_typehints = 'description'
autodoc_typehints_description_target = 'documented'
autodoc_class_signature = 'separated'
# -- Options for Napoleon (Google/NumPy docstrings) -------------------------
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = True
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = True
napoleon_use_admonition_for_notes = True
napoleon_use_admonition_for_references = True
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_use_keyword = True
napoleon_attr_annotations = True
# -- Options for intersphinx -------------------------------------------------
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'numpy': ('https://numpy.org/doc/stable/', None),
'pandas': ('https://pandas.pydata.org/docs/', None),
'requests': ('https://requests.readthedocs.io/en/latest/', None),
}
# -- Options for todo extension ----------------------------------------------
todo_include_todos = True
# -- Options for LaTeX/PDF output --------------------------------------------
latex_elements = {
'papersize': 'letterpaper',
'pointsize': '11pt',
'preamble': r'''
\usepackage{charter}
\usepackage[defaultsans]{lato}
\usepackage{inconsolata}
''',
}
latex_documents = [
(master_doc, 'MyProject.tex', 'MyProject Documentation',
'Your Name', 'manual'),
]
# -- Options for EPUB output -------------------------------------------------
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
epub_exclude_files = ['search.html']
3. Index and Table of Contents
.. docs/source/index.rst
Welcome to MyProject
====================
MyProject is a powerful library for doing amazing things.
.. toctree::
:maxdepth: 2
:caption: Getting Started
installation
quickstart
configuration
.. toctree::
:maxdepth: 2
:caption: User Guide
guide/overview
guide/core-concepts
guide/advanced-usage
guide/best-practices
.. toctree::
:maxdepth: 3
:caption: API Reference
api/modules
api/mypackage
.. toctree::
:maxdepth: 1
:caption: Development
contributing
changelog
license
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
4. Autodoc - Automatic API Documentation
# src/mypackage/core.py
"""
Core module for MyPackage.
This module provides the main classes and functions for
data processing and analysis.
Example:
Basic usage of the module::
from mypackage.core import DataProcessor
processor = DataProcessor()
result = processor.process(data)
"""
from typing import Any, Dict, List, Optional, Union
from pathlib import Path
class DataProcessor:
"""
A class for processing and analyzing data.
This processor supports multiple data formats and provides
methods for validation, transformation, and export.
Attributes:
config: Configuration dictionary for the processor.
verbose: Whether to print verbose output.
_cache: Internal cache for processed results.
Example:
>>> processor = DataProcessor(verbose=True)
>>> processor.load("data.csv")
>>> result = processor.process()
"""
def __init__(
self,
config: Optional[Dict[str, Any]] = None,
verbose: bool = False
) -> None:
"""
Initialize the DataProcessor.
Args:
config: Optional configuration dictionary. If not provided,
defaults will be used. Keys include:
- ``max_rows``: Maximum rows to process (default: 10000)
- ``encoding``: File encoding (default: 'utf-8')
- ``delimiter``: CSV delimiter (default: ',')
verbose: If True, print progress information during
processing. Defaults to False.
Raises:
ValueError: If config contains invalid keys.
Example:
>>> config = {'max_rows': 5000, 'encoding': 'utf-8'}
>>> processor = DataProcessor(config=config, verbose=True)
"""
self.config = config or {}
self.verbose = verbose
self._cache: Dict[str, Any] = {}
def load(
self,
path: Union[str, Path],
*,
validate: bool = True
) -> 'DataProcessor':
"""
Load data from a file.
Supports CSV, JSON, and Parquet formats. The format is
automatically detected from the file extension.
Args:
path: Path to the data file. Can be a string or
:class:`pathlib.Path` object.
validate: Whether to validate data after loading.
Defaults to True.
Returns:
Self for method chaining.
Raises:
FileNotFoundError: If the file does not exist.
ValueError: If the file format is not supported.
Example:
>>> processor = DataProcessor()
>>> processor.load("input.csv", validate=True)
<DataProcessor object>
See Also:
:meth:`save`: Save processed data to file.
:meth:`validate`: Validate loaded data.
Note:
Large files (>1GB) may require additional memory.
Consider using chunked processing for such files.
"""
# Implementation here
return self
def process(
self,
operations: Optional[List[str]] = None
) -> Dict[str, Any]:
"""
Process the loaded data with specified operations.
Args:
operations: List of operation names to apply.
Available operations:
- ``'clean'``: Remove null values
- ``'normalize'``: Normalize numeric columns
- ``'aggregate'``: Compute aggregations
If None, all operations are applied.
Returns:
Dictionary containing:
- ``data``: Processed data
- ``stats``: Processing statistics
- ``errors``: List of any errors encountered
Raises:
RuntimeError: If no data has been loaded.
Warning:
This method modifies the internal data state.
Use :meth:`copy` first if you need the original.
Example:
>>> processor.load("data.csv")
>>> result = processor.process(['clean', 'normalize'])
>>> print(result['stats'])
{'rows_processed': 1000, 'time_ms': 42}
"""
return {'data': None, 'stats': {}, 'errors': []}
def save(
self,
path: Union[str, Path],
format: str = 'csv'
) -> None:
"""
Save processed data to a file.
Args:
path: Output file path.
format: Output format. One of:
- ``'csv'``: Comma-separated values
- ``'json'``: JSON format
- ``'parquet'``: Apache Parquet format
Raises:
ValueError: If format is not supported.
IOError: If file cannot be written.
Example:
>>> processor.process()
>>> processor.save("output.csv", format='csv')
"""
pass
def calculate_metrics(
data: List[float],
*,
include_variance: bool = False
) -> Dict[str, float]:
"""
Calculate statistical metrics for a list of values.
This function computes common statistical measures
for the provided data.
Args:
data: List of numeric values to analyze.
include_variance: Whether to include variance
in the results. Defaults to False.
Returns:
Dictionary with the following keys:
- ``mean``: Arithmetic mean
- ``median``: Median value
- ``min``: Minimum value
- ``max``: Maximum value
- ``variance``: (optional) Population variance
Raises:
ValueError: If data is empty.
TypeError: If data contains non-numeric values.
Example:
>>> metrics = calculate_metrics([1, 2, 3, 4, 5])
>>> print(metrics['mean'])
3.0
Note:
For large datasets (>1M values), consider using
NumPy functions for better performance.
"""
if not data:
raise ValueError("Data cannot be empty")
result = {
'mean': sum(data) / len(data),
'median': sorted(data)[len(data) // 2],
'min': min(data),
'max': max(data),
}
if include_variance:
mean = result['mean']
result['variance'] = sum((x - mean) ** 2 for x in data) / len(data)
return result
.. docs/source/api/mypackage.rst
mypackage package
=================
.. automodule:: mypackage
:members:
:undoc-members:
:show-inheritance:
mypackage.core module
---------------------
.. automodule:: mypackage.core
:members:
:undoc-members:
:show-inheritance:
mypackage.utils module
----------------------
.. automodule:: mypackage.utils
:members:
:undoc-members:
:show-inheritance:
5. Generate API Documentation
# Auto-generate API documentation stubs
sphinx-apidoc -o docs/source/api src/mypackage -f -e -M
# Options:
# -o: Output directory
# -f: Force overwrite
# -e: Separate pages for each module
# -M: Module-first ordering
# -d 2: TOC depth
# Build HTML documentation
sphinx-build -b html docs/source docs/build/html
# Build with verbose output
sphinx-build -b html docs/source docs/build/html -v
# Clean and rebuild
rm -rf docs/build && sphinx-build -b html docs/source docs/build/html
6. MyST Markdown Support
# conf.py - Enable MyST
extensions = [
'myst_parser',
]
# MyST configuration
myst_enable_extensions = [
'amsmath',
'colon_fence',
'deflist',
'dollarmath',
'fieldlist',
'html_admonition',
'html_image',
'replacements',
'smartquotes',
'strikethrough',
'substitution',
'tasklist',
]
myst_heading_anchors = 3
myst_footnote_transition = True
<!-- docs/source/guide/overview.md -->
# Overview
This guide provides an overview of MyProject.
## Features
MyProject includes the following features:
- Fast data processing
- Multiple format support
- Extensible architecture
## Quick Example
```{code-block} python
:linenos:
:emphasize-lines: 2,4
from mypackage import DataProcessor
processor = DataProcessor()
result = processor.process(data)
Admonitions
This is a note admonition in MyST syntax.
Be careful with this operation!
Use this feature for better performance.
Cross-References
See the {ref}installation guide for setup instructions.
Check the {py:class}mypackage.core.DataProcessor class reference.
Math Support
Inline math: $E = mc^2$
Display math:
$$ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$
Task Lists
- Write documentation
- Add code examples
- Review and publish
Definition Lists
Term 1 : Definition for term 1
Term 2 : Definition for term 2
### 7. Intersphinx Cross-References
```python
# conf.py
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'numpy': ('https://numpy.org/doc/stable/', None),
'pandas': ('https://pandas.pydata.org/docs/', None),
'scipy': ('https://docs.scipy.org/doc/scipy/', None),
'matplotlib': ('https://matplotlib.org/stable/', None),
'sklearn': ('https://scikit-learn.org/stable/', None),
}
# Timeout for fetching inventory files
intersphinx_timeout = 30
.. Usage in documentation
Using NumPy Arrays
------------------
This function accepts :class:`numpy.ndarray` objects.
See :func:`numpy.array` for creating arrays.
The algorithm is based on :meth:`pandas.DataFrame.groupby`.
For plotting, use :func:`matplotlib.pyplot.plot`.
8. Multiple Output Formats
# Build HTML
sphinx-build -b html docs/source docs/build/html
# Build PDF (requires LaTeX)
sphinx-build -b latex docs/source docs/build/latex
cd docs/build/latex && make
# Build ePub
sphinx-build -b epub docs/source docs/build/epub
# Build man pages
sphinx-build -b man docs/source docs/build/man
# Build single HTML file
sphinx-build -b singlehtml docs/source docs/build/singlehtml
# Build plain text
sphinx-build -b text docs/source docs/build/text
# Check for broken links
sphinx-build -b linkcheck docs/source docs/build/linkcheck
# Check documentation coverage
sphinx-build -b coverage docs/source docs/build/coverage
# conf.py - PDF customization
latex_engine = 'xelatex'
latex_elements = {
'papersize': 'a4paper',
'pointsize': '11pt',
'figure_align': 'htbp',
'preamble': r'''
\usepackage{charter}
\usepackage[defaultsans]{lato}
\usepackage{inconsolata}
% Custom chapter styling
\usepackage{titlesec}
\titleformat{\chapter}[display]
{\normalfont\huge\bfseries}
{\chaptertitlename\ \thechapter}{20pt}{\Huge}
% Code block styling
\usepackage{fancyvrb}
\fvset{fontsize=\small}
''',
'maketitle': r'''
\begin{titlepage}
\centering
\vspace*{2cm}
{\Huge\bfseries MyProject Documentation\par}
\vspace{1cm}
{\Large Version 1.0.0\par}
\vspace{2cm}
{\large Your Name\par}
\vfill
{\large \today\par}
\end{titlepage}
''',
}
latex_documents = [
(master_doc, 'myproject.tex', 'MyProject Documentation',
'Your Name', 'manual', True),
]
latex_show_urls = 'footnote'
latex_show_pagerefs = True
9. Read the Docs Configuration
# .readthedocs.yaml
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.11"
jobs:
pre_build:
- pip install -e ".[docs]"
sphinx:
configuration: docs/source/conf.py
fail_on_warning: true
python:
install:
- requirements: docs/requirements.txt
- method: pip
path: .
extra_requirements:
- docs
formats:
- pdf
- epub
# docs/requirements.txt
sphinx>=7.0.0
sphinx-rtd-theme>=2.0.0
sphinx-autodoc-typehints>=1.25.0
sphinx-copybutton>=0.5.0
myst-parser>=2.0.0
sphinxcontrib-mermaid>=0.9.0
10. Custom Extensions
# docs/source/_extensions/custom_directive.py
from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx.application import Sphinx
class VersionAddedDirective(Directive):
"""
Custom directive to mark version additions.
Usage::
.. versionadded:: 1.2.0
This feature was added in version 1.2.0.
"""
required_arguments = 1
optional_arguments = 0
has_content = True
def run(self):
version = self.arguments[0]
content = '\n'.join(self.content)
para = nodes.paragraph()
para += nodes.strong(text=f'New in version {version}: ')
para += nodes.Text(content)
container = nodes.container(classes=['versionadded'])
container += para
return [container]
class APIEndpointDirective(Directive):
"""
Custom directive for API endpoints.
Usage::
.. api-endpoint:: GET /api/v1/users
Retrieve list of users.
:param page: Page number
:param limit: Items per page
:returns: JSON array of users
"""
required_arguments = 1
optional_arguments = 0
has_content = True
option_spec = {
'deprecated': lambda x: x,
}
def run(self):
method_path = self.arguments[0]
parts = method_path.split(' ', 1)
method = parts[0] if len(parts) > 0 else 'GET'
path = parts[1] if len(parts) > 1 else '/'
# Create container
container = nodes.container(classes=['api-endpoint'])
# Add method badge
method_node = nodes.literal(text=method, classes=[f'method-{method.lower()}'])
path_node = nodes.literal(text=path, classes=['endpoint-path'])
header = nodes.paragraph()
header += method_node
header += nodes.Text(' ')
header += path_node
container += header
# Add content
if self.content:
content = nodes.container()
self.state.nested_parse(self.content, self.content_offset, content)
container += content
return [container]
def setup(app: Sphinx):
app.add_directive('versionadded', VersionAddedDirective)
app.add_directive('api-endpoint', APIEndpointDirective)
return {
'version': '1.0.0',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
# conf.py - Register custom extension
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent / '_extensions'))
extensions = [
# ... other extensions
'custom_directive',
]
11. GitHub Actions Deployment
# .github/workflows/docs.yml
name: Documentation
on:
push:
branches: [main]
paths:
- 'docs/**'
- 'src/**/*.py'
- '.github/workflows/docs.yml'
pull_request:
paths:
- 'docs/**'
- 'src/**/*.py'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install dependencies
run: |
pip install -e ".[docs]"
pip install -r docs/requirements.txt
- name: Build documentation
run: |
cd docs
sphinx-build -b html source build/html -W --keep-going
- name: Check links
run: |
cd docs
sphinx-build -b linkcheck source build/linkcheck
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: documentation
path: docs/build/html
deploy:
needs: build
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: documentation
path: docs/build/html
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/build/html
12. API Documentation with sphinx-autoapi
# conf.py - Using sphinx-autoapi (alternative to autodoc)
extensions = [
'autoapi.extension',
]
# AutoAPI configuration
autoapi_type = 'python'
autoapi_dirs = ['../../src/mypackage']
autoapi_template_dir = '_templates/autoapi'
autoapi_options = [
'members',
'undoc-members',
'show-inheritance',
'show-module-summary',
'special-members',
'imported-members',
]
autoapi_python_class_content = 'both'
autoapi_member_order = 'groupwise'
autoapi_root = 'api'
autoapi_keep_files = True
autoapi_add_toctree_entry = True
# Suppress autodoc if using autoapi
autodoc_default_options = {}
Integration Examples
Integration with pyproject.toml
# pyproject.toml
[project]
name = "mypackage"
version = "1.0.0"
description = "A Python package with Sphinx docs"
readme = "README.md"
requires-python = ">=3.8"
[project.optional-dependencies]
docs = [
"sphinx>=7.0.0",
"sphinx-rtd-theme>=2.0.0",
"sphinx-autodoc-typehints>=1.25.0",
"sphinx-copybutton>=0.5.0",
"myst-parser>=2.0.0",
]
[tool.setuptools.packages.find]
where = ["src"]
Integration with Makefile
# docs/Makefile
SPHINXOPTS ?= -W --keep-going
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
.PHONY: help clean html pdf epub linkcheck livehtml
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
clean:
rm -rf $(BUILDDIR)/*
html:
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
@echo "Build finished. Open $(BUILDDIR)/html/index.html"
pdf:
@$(SPHINXBUILD) -b latex "$(SOURCEDIR)" "$(BUILDDIR)/latex" $(SPHINXOPTS)
@$(MAKE) -C "$(BUILDDIR)/latex" all-pdf
@echo "Build finished. PDF at $(BUILDDIR)/latex/*.pdf"
epub:
@$(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)/epub" $(SPHINXOPTS)
@echo "Build finished. EPUB at $(BUILDDIR)/epub/*.epub"
linkcheck:
@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
livehtml:
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
Integration with Pre-commit
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: sphinx-build
name: Build Sphinx documentation
entry: sphinx-build -b html docs/source docs/build/html -W
language: system
pass_filenames: false
types: [python, rst, markdown]
Best Practices
1. Docstring Style Guide
# Use Google style (recommended)
def function(arg1: str, arg2: int = 10) -> bool:
"""
Short description of function.
Longer description that provides more detail about
what the function does and how it works.
Args:
arg1: Description of arg1.
arg2: Description of arg2. Defaults to 10.
Returns:
Description of return value.
Raises:
ValueError: If arg1 is empty.
TypeError: If arg2 is not an integer.
Example:
>>> function("hello", 5)
True
Note:
Additional notes about usage.
See Also:
related_function: Description of related function.
"""
pass
2. Documentation Structure
docs/
├── source/
│ ├── _static/
│ │ ├── css/
│ │ │ └── custom.css
│ │ └── images/
│ ├── _templates/
│ │ └── layout.html
│ ├── api/
│ │ ├── index.rst
│ │ └── modules.rst
│ ├── guide/
│ │ ├── installation.rst
│ │ ├── quickstart.rst
│ │ └── advanced.rst
│ ├── tutorials/
│ │ └── basic.rst
│ ├── conf.py
│ ├── index.rst
│ └── changelog.rst
├── build/
├── Makefile
└── requirements.txt
3. Cross-Reference Best Practices
.. Use these reference styles
Classes and Methods
~~~~~~~~~~~~~~~~~~~
See :class:`mypackage.core.DataProcessor` for the main class.
Use :meth:`~mypackage.core.DataProcessor.process` method.
The :attr:`mypackage.core.DataProcessor.config` attribute.
Functions
~~~~~~~~~
Call :func:`mypackage.utils.helper` for utility functions.
Modules
~~~~~~~
Import from :mod:`mypackage.core` module.
External References
~~~~~~~~~~~~~~~~~~~
Uses :class:`numpy.ndarray` for array storage.
See :func:`pandas.read_csv` for file loading.
4. Version Documentation
.. Document version changes
API Changes
-----------
.. versionadded:: 1.2.0
Added support for Parquet format.
.. versionchanged:: 1.3.0
The ``format`` parameter now defaults to ``'auto'``.
.. deprecated:: 2.0.0
Use :meth:`new_method` instead. Will be removed in v3.0.
.. versionremoved:: 2.0.0
The ``old_param`` parameter has been removed.
Troubleshooting
Common Issues
Autodoc Cannot Find Module
# conf.py - Add source to path
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parents[2] / 'src'))
Intersphinx Inventory Not Loading
# conf.py - Use local inventory file
intersphinx_mapping = {
'python': ('https://docs.python.org/3', 'python-objects.inv'),
}
# Download inventory manually
# curl -O https://docs.python.org/3/objects.inv
Build Warnings as Errors
# Build without -W flag for debugging
sphinx-build -b html docs/source docs/build/html
# Then fix warnings before re-enabling
sphinx-build -b html docs/source docs/build/html -W
Napoleon Not Parsing Docstrings
# conf.py - Ensure napoleon is configured
napoleon_google_docstring = True
napoleon_numpy_docstring = True
# Check docstring format - must have proper indentation
def func():
"""
Summary line.
Args:
param: Description. # Note: proper indentation
"""
PDF Build Fails
# Install full LaTeX distribution
# Ubuntu
sudo apt-get install texlive-full
# macOS
brew install --cask mactex
# Check LaTeX installation
pdflatex --version
latexmk --version
Debug Mode
# Verbose build
sphinx-build -b html docs/source docs/build/html -v
# Very verbose
sphinx-build -b html docs/source docs/build/html -vvv
# Show traceback on errors
sphinx-build -b html docs/source docs/build/html -T
# Keep going on errors
sphinx-build -b html docs/source docs/build/html --keep-going
Version History
v1.0.0 (2026-01-17)
- Initial skill creation
- Autodoc configuration for Python API
- Napoleon support for Google/NumPy docstrings
- Intersphinx cross-references
- Multiple output formats (HTML, PDF, ePub)
- Read the Docs configuration
- MyST Markdown support
- Custom extensions guide
- GitHub Actions deployment
Related Resources
- Sphinx Documentation
- Read the Docs
- Napoleon Extension
- MyST Parser
- Sphinx Themes Gallery
- Google Python Style Guide
Generate comprehensive Python documentation with automatic API extraction and professional output formats.
Weekly Installs
10
Repository
vamseeachanta/workspace-hubFirst Seen
Jan 24, 2026
Security Audits
Installed on
claude-code9
antigravity8
windsurf8
codex8
trae8
opencode8