Generate comprehensive Python documentation with Sphinx. Covers autodoc for API extraction, Napoleon for Google/NumPy docstrings, intersphinx for cross-references, and multiple output formats including HTML, PDF, and ePub.
Generate comprehensive Python documentation with Sphinx. Covers autodoc for API extraction, Napoleon for Google/NumPy docstrings, intersphinx for cross-references, and multiple output formats including HTML, PDF, and ePub.
version
1.0.0
category
documentation
type
skill
capabilities
["Automatic API documentation from docstrings","reStructuredText and MyST Markdown support","Napoleon extension for Google/NumPy docstrings","Cross-project references with intersphinx","Multiple output formats (HTML, PDF, ePub, man pages)","Read the Docs theme integration","Code documentation with viewcode","Type hint documentation with autodoc_typehints","Custom domain extensions","Internationalization (i18n) support"]
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
-p docs/source docs/build
docs/source/conf.py docs/source/index.rst
.. 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 importAny, Dict, List, Optional, Unionfrom pathlib import Path
classDataProcessor:
"""
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] = {}
defload(
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 herereturnselfdefprocess(
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': []}
defsave(
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')
"""passdefcalculate_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.
"""ifnot 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) ** 2for x in data) / len(data)
return result
<!-- 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.
.. 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
# Use Google style (recommended)deffunction(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
.. 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 pathimport sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parents[2] / 'src'))
# 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 indentationdeffunc():
"""
Summary line.
Args:
param: Description. # Note: proper indentation
"""
# 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
