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

: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.