sphinx

What this skill does

# 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

```bash
# 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

```bash
# 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)

```python
# 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

```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

```python
# 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