tessl/pypi-pdoc

API Documentation for Python Projects with focus on simplicity and automatic HTML generation from docstrings

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

pdoc

Name: tessl/pypi-pdoc
Author: tessl

API Documentation for Python Projects with focus on simplicity and automatic HTML generation from docstrings. pdoc auto-generates clean, readable API documentation directly from Python source code by analyzing type annotations, docstrings, and module structures using abstract syntax tree parsing.

Package Information

Package Name: pdoc
Language: Python
Installation: pip install pdoc
Python Support: Python 3.9+

Core Imports

import pdoc

For main functionality:

from pdoc import pdoc

For documentation object access:

from pdoc import doc, extract, render

Basic Usage

Command Line Interface

# Generate documentation for a module
pdoc your_module

# Generate documentation for a file
pdoc ./my_project.py

# Save to HTML files
pdoc your_module -o ./docs

# Start development server with live reload
pdoc your_module --host localhost --port 8080

Programmatic API

import pdoc

# Generate documentation for modules
html_output = pdoc.pdoc("my_module")  # Returns HTML string

# Save to directory
pdoc.pdoc("my_module", output_directory="./docs")  # Writes HTML files

# Configure rendering options
pdoc.render.configure(
    docformat="google",  # Support Google-style docstrings
    show_source=True,    # Include source code links
    math=True            # Enable math formula rendering
)

Architecture

pdoc follows a modular architecture with clear separation of concerns:

Module Extraction: Discovers and loads Python modules safely while handling import errors
Documentation Objects: Represents Python constructs (modules, classes, functions) as structured objects
AST Processing: Analyzes source code using Python's abstract syntax tree for accurate type and signature extraction
Docstring Processing: Converts various docstring formats (Markdown, Google, NumPy, reStructuredText) to HTML
HTML Rendering: Template-based HTML generation with customizable Jinja2 templates
Web Server: Built-in development server with live reloading and automatic regeneration

Capabilities

Main Documentation Generation

Core functionality for generating documentation from Python modules using the primary pdoc() function with flexible output options.

def pdoc(*modules: Path | str, output_directory: Path | None = None) -> str | None:
    """
    Render documentation for modules.
    
    Parameters:
    - modules: Module names or file paths to document
    - output_directory: Directory for HTML output (None returns HTML string)
    
    Returns:
    - HTML string if output_directory is None, else None
    """

Main API

Documentation Objects

Object model for representing Python modules, classes, functions, and variables with their metadata, signatures, and docstrings.

class Module(Namespace):
    """Module documentation object"""
    @classmethod
    def from_name(cls, module_name: str) -> 'Module': ...

class Class(Namespace):
    """Class documentation object"""
    pass

class Function(Doc):
    """Function/method documentation object"""
    pass

class Variable(Doc):
    """Variable/attribute documentation object"""
    pass

Documentation Objects

Module Extraction and Loading

Utilities for discovering, loading, and walking Python modules with error handling and import safety.

def walk_specs(modules: Iterable[Path | str]) -> Iterator[str]: ...
def load_module(module_name: str) -> ModuleType: ...
def parse_spec(spec: str) -> tuple[str, bool]: ...
def walk_packages2(paths: list[str], prefix: str = "") -> Iterator[ModuleInfo]: ...

Module Extraction

HTML Rendering and Templates

Template-based HTML generation system with customizable Jinja2 templates and rendering configuration options.

def configure(
    docformat: str = "restructuredtext",
    show_source: bool = True,
    math: bool = False,
    mermaid: bool = False,
    **kwargs
) -> None: ...

def html_module(module: doc.Module, all_modules: dict[str, doc.Module]) -> str: ...
def html_index(all_modules: dict[str, doc.Module]) -> str: ...

HTML Rendering

Docstring Processing

Multi-format docstring conversion supporting Markdown, Google, NumPy, and reStructuredText styles with cross-reference linking.

def convert(docstring: str, docformat: str = "restructuredtext") -> str: ...
def google(text: str) -> str: ...
def numpy(text: str) -> str: ...
def rst(text: str) -> str: ...

Docstring Processing

Web Development Server

Built-in HTTP server for documentation development with live reloading and automatic regeneration on source changes.

class DocServer:
    """HTTP server for serving documentation with live reload"""
    def __init__(self, addr: tuple[str, int], **kwargs): ...
    def serve_forever(self): ...

def open_browser(url: str) -> None: ...

Web Server

AST Processing and Source Analysis

Abstract syntax tree processing for extracting Python code structure, type annotations, and source code metadata.

def parse(obj: Any) -> ast.AST | None: ...
def get_source(obj: Any) -> str | None: ...
def unparse(tree: ast.AST) -> str: ...
def sort_by_source(items: list[Doc]) -> list[Doc]: ...

AST Processing

Search Functionality

Client-side search index generation for fast documentation search capabilities in rendered HTML output.

def make_index(all_modules: dict[str, doc.Module]) -> dict: ...
def search_index(all_modules: dict[str, doc.Module]) -> str: ...

Command Line Interface

Comprehensive command-line interface for generating documentation with extensive customization options and development server capabilities.

def cli(args: list[str] | None = None) -> None:
    """
    Command-line interface entry point.
    
    Parameters:
    - args: Command line arguments (uses sys.argv if None)
    
    Features:
    - Module specification parsing
    - Output format selection
    - Development server with live reload
    - Template and styling customization
    """

def get_dev_version() -> str:
    """
    Get development version string with git commit information.
    
    Returns:
    - str: Version string with git commit hash if in development
    """

CLI Interface

Types

class Doc:
    """Base documentation object"""
    name: str
    qualname: str
    fullname: str
    obj: Any
    taken_from: tuple[str, str]
    
class Namespace(Doc):
    """Base class for modules and classes"""
    members: dict[str, Doc]
    
class ModuleInfo:
    """Module discovery information"""
    module_finder: MetaPathFinder
    name: str
    ispkg: bool