How do I create documentation from doc strings in Python?

Python provides several tools to automatically generate documentation from docstrings in your code. The three most popular tools are Pydoc, Epydoc, and Sphinx, each offering different features and output formats.

Pydoc

Pydoc is Python's built-in documentation generator that creates HTML pages from docstrings in your source code. It's included with Python, so no additional installation is required.

Basic Usage

First, let's create a simple Python module with docstrings ?

def calculate_area(length, width):
    """
    Calculate the area of a rectangle.
    
    Args:
        length (float): The length of the rectangle
        width (float): The width of the rectangle
    
    Returns:
        float: The area of the rectangle
    """
    return length * width

class Calculator:
    """A simple calculator class for basic arithmetic operations."""
    
    def add(self, x, y):
        """Add two numbers and return the result."""
        return x + y
    
    def multiply(self, x, y):
        """Multiply two numbers and return the result."""
        return x * y

print("Module created successfully!")

Module created successfully!

Command Line Usage

Pydoc can be used from the command line to generate documentation. Here are the most common commands ?

# Display documentation in terminal
pydoc sys

# Start HTTP server for browsing documentation
pydoc -b

# Start server on specific hostname
pydoc -n localhost

# Generate HTML file
pydoc -w module_name

The help() function in Python's interactive interpreter uses pydoc internally to display documentation.

Epydoc

Epydoc generates API documentation from docstrings and supports multiple markup formats including Epytext, reStructuredText, and Javadoc.

Installation and Features

# Install epydoc
pip install epydoc

# Generate HTML documentation
epydoc --html -o docs/ mymodule.py

# Generate PDF documentation  
epydoc --pdf -o docs/ mymodule.py

Epydoc supports advanced markup in docstrings for better formatting and can generate both HTML and PDF output formats.

Sphinx

Sphinx is the most powerful documentation tool, widely used for Python projects. It offers extensive customization and multiple output formats.

Key Features

• Multiple Output Formats HTML, LaTeX, ePub, PDF, manual pages
• Cross-references Automatic links between functions, classes, and modules
• Extensions Autodoc for extracting docstrings, code highlighting
• Themes Professional-looking customizable templates
• Hierarchical Structure Organize documentation in a tree structure

Basic Sphinx Setup

# Install Sphinx
pip install sphinx

# Initialize Sphinx project
sphinx-quickstart

# Build HTML documentation
make html

# Build PDF documentation
make latexpdf

Comparison

Conclusion

Use Pydoc for quick documentation generation, Epydoc for API documentation with advanced markup, and Sphinx for comprehensive project documentation with professional formatting and multiple output formats.