Sphinx

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.