tessl/pypi-pdoc3

Auto-generate API documentation for Python projects with support for multiple docstring formats, type annotations, and customizable templates.

—

Pending

Overview

Eval results

Files

Core Documentation API

Name: tessl/pypi-pdoc3
Author: tessl

The main API for generating documentation from Python source code. These functions provide the primary interface for programmatic documentation generation with various output formats and customization options.

Capabilities

HTML Documentation Generation

Generate self-contained HTML documentation from Python modules with full styling, cross-linking, and optional minification.

def html(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str:
    """
    Returns the documentation for the module in HTML format.
    
    Parameters:
    - module_name: Module name or importable string
    - docfilter: Optional predicate function that controls which documentation 
                objects are shown (takes Doc object, returns bool)
    - reload: If True, reload the module before generating documentation
    - skip_errors: If True, warn instead of raising on import errors
    - **kwargs: Additional template configuration options
    
    Returns:
    str: Self-contained HTML documentation
    """

Text Documentation Generation

Generate plain text documentation suitable for terminal viewing or text-based documentation systems.

def text(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str:
    """
    Returns the documentation for the module in plain text format.
    
    Parameters:
    - module_name: Module name or importable string
    - docfilter: Optional predicate function for filtering documentation objects
    - reload: If True, reload the module before generating documentation
    - skip_errors: If True, warn instead of raising on import errors
    - **kwargs: Additional template configuration options
    
    Returns:
    str: Plain text documentation suitable for terminal viewing
    """

Module Import and Management

Import and manage Python modules for documentation processing with support for filesystem paths and error handling.

def import_module(module, reload=False, skip_errors=False) -> ModuleType:
    """
    Return module object matching module specification.
    
    Parameters:
    - module: Module specification (python module path or filesystem path)
    - reload: If True, reload module if already imported
    - skip_errors: If True, warn instead of raising on import errors
    
    Returns:
    ModuleType: Imported module object
    """

Context and State Management

Manage global documentation context and reset caches for clean documentation generation.

def reset() -> None:
    """
    Resets the global Context to the initial (empty) state.
    
    Clears all cached documentation objects and LRU caches for:
    - Type hints cache
    - Blacklist/whitelist caches  
    - Doc object method caches
    """

def link_inheritance(context=None) -> None:
    """
    Link inheritance relationships between Class objects and their members.
    
    Parameters:
    - context: Optional Context to use (defaults to global context)
    
    This must be called for Doc.inherits and inherited docstrings to be set correctly.
    """

Module Documentation Objects

Create and manipulate Module objects for advanced documentation processing and customization.

class Module(Doc):
    def __init__(self, module, docfilter=None, supermodule=None, context=None, skip_errors=False):
        """
        Creates a Module documentation object.
        
        Parameters:
        - module: Module object or importable string
        - docfilter: Optional predicate that controls which sub-objects are documented
        - supermodule: Parent Module if this is a submodule
        - context: Context instance for cross-referencing (defaults to global)
        - skip_errors: If True, warn instead of raising on unimportable submodules
        """
    
    def html(self, minify=True, **kwargs) -> str:
        """
        Returns HTML documentation for this module.
        
        Parameters:
        - minify: If True, minify the resulting HTML
        - **kwargs: Template configuration options
        
        Returns:
        str: Self-contained HTML documentation
        """
    
    def text(self, **kwargs) -> str:
        """
        Returns plain text documentation for this module.
        
        Parameters:
        - **kwargs: Template configuration options
        
        Returns:
        str: Plain text documentation
        """
    
    def find_class(self, cls: type) -> Doc:
        """
        Find a class documentation object in this module or submodules.
        
        Parameters:
        - cls: Python class object
        
        Returns:
        Doc: Class documentation object or External if not found
        """
    
    def find_ident(self, name: str) -> Doc:
        """
        Find identifier documentation object by name.
        
        Parameters:
        - name: Identifier name to search for
        
        Returns:
        Doc: Documentation object or External if not found
        """
    
    def variables(self, sort=True) -> List['Variable']:
        """
        Returns all documented module-level variables.
        
        Parameters:
        - sort: If True, sort alphabetically
        
        Returns:
        List[Variable]: Module variables
        """
    
    def classes(self, sort=True) -> List['Class']:
        """
        Returns all documented module-level classes.
        
        Parameters:
        - sort: If True, sort alphabetically
        
        Returns:
        List[Class]: Module classes
        """
    
    def functions(self, sort=True) -> List['Function']:
        """
        Returns all documented module-level functions.
        
        Parameters:
        - sort: If True, sort alphabetically
        
        Returns:
        List[Function]: Module functions
        """
    
    def submodules(self) -> List['Module']:
        """
        Returns all documented sub-modules sorted alphabetically.
        
        Returns:
        List[Module]: Submodules
        """

Context Management

Global context for cross-referencing between documentation objects and modules.

class Context(dict):
    def __init__(self, *args, **kwargs):
        """
        Context object that maps documented identifiers to their Doc objects.
        
        All Module objects that share the same Context will see and be able
        to link to each other's identifiers.
        """

Usage Examples

Basic Documentation Generation

import pdoc

# Generate documentation for a single module
doc = pdoc.html('numpy')

# Generate with custom filter to exclude private members
def public_only(doc_obj):
    return not doc_obj.name.startswith('_')

filtered_doc = pdoc.html('mymodule', docfilter=public_only)

Advanced Module Processing

import pdoc

# Create shared context for multiple modules
context = pdoc.Context()

# Process multiple related modules
modules = []
for module_name in ['mypackage.core', 'mypackage.utils', 'mypackage.api']:
    module = pdoc.Module(module_name, context=context)
    modules.append(module)

# Link inheritance across all modules
pdoc.link_inheritance(context)

# Generate documentation for each module
for module in modules:
    html_doc = module.html(show_source=True, external_links=True)
    with open(f'{module.name}.html', 'w') as f:
        f.write(html_doc)

Error Handling and Debugging

import pdoc

try:
    # Attempt to generate documentation
    doc = pdoc.html('problematic_module')
except ImportError as e:
    print(f"Import failed: {e}")
    # Use skip_errors to continue processing
    doc = pdoc.html('problematic_module', skip_errors=True)

# Reset global state between runs
pdoc.reset()

Install with Tessl CLI