or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcore-api.mddoc-objects.mdhtml-processing.mdindex.md
tile.json

tessl/pypi-pdoc3

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pdoc3@0.11.x

To install, run

npx @tessl/cli install tessl/pypi-pdoc3@0.11.0

index.mddocs/

pdoc3

Auto-generates API documentation for Python 3+ projects from source code and docstrings. pdoc3 provides comprehensive documentation generation with support for multiple docstring formats (Markdown, numpydoc, Google-style), type annotations (PEP 484/526), automatic cross-linking, docstring inheritance, customizable templates, and a built-in development web server for real-time preview.

Package Information

  • Package Name: pdoc3
  • Language: Python
  • Installation: pip install pdoc3
  • Python Requirements: Python 3.9+

Core Imports

import pdoc

For CLI usage:

from pdoc.cli import main

For HTML processing utilities:

from pdoc.html_helpers import to_html, to_markdown

Basic Usage

Simple Documentation Generation

import pdoc

# Generate HTML documentation for a module
html_doc = pdoc.html('mymodule')

# Generate plain text documentation
text_doc = pdoc.text('mymodule')

# Save to file
with open('mymodule.html', 'w') as f:
    f.write(html_doc)

Advanced Usage with Module Objects

import pdoc

# Create Module documentation object
module = pdoc.Module('mymodule')

# Link inheritance relationships for complete documentation
pdoc.link_inheritance()

# Generate HTML with custom template configuration
html_doc = module.html(
    minify=True,
    show_source=True,
    external_links=True
)

Command Line Usage

from pdoc.cli import main

# Generate HTML documentation
main(['mymodule', '--html', '--output-dir', './docs'])

# Start development server
main(['mymodule', '--http', ':8080'])

# Generate documentation with custom template
main(['mymodule', '--html', '--template-dir', './templates'])

Architecture

pdoc3 is built around a hierarchical documentation object model:

  • Doc: Base class for all documentation objects with common properties (name, module, docstring, etc.)
  • Module: Represents module documentation, handles package traversal and submodule discovery
  • Class: Represents class documentation with inheritance analysis and member organization
  • Function: Represents function/method documentation with signature analysis and parameter handling
  • Variable: Represents variable documentation (module, class, or instance variables)
  • External: Represents external/undocumented identifiers for cross-referencing
  • Context: Global registry mapping identifiers to documentation objects for cross-linking

The template system uses Mako templates for customizable HTML and text output generation, while the CLI provides both batch processing and interactive development server capabilities.

Capabilities

Core Documentation API

Generate documentation programmatically using the main API functions and Module objects. Supports filtering, template customization, and various output formats.

def html(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str: ...
def text(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str: ...
def import_module(module, reload=False, skip_errors=False) -> ModuleType: ...
def reset() -> None: ...
def link_inheritance(context=None) -> None: ...

class Module:
    def __init__(self, module, docfilter=None, supermodule=None, context=None, skip_errors=False): ...
    def html(self, minify=True, **kwargs) -> str: ...
    def text(self, **kwargs) -> str: ...

Core Documentation API

Documentation Objects

Work with individual documentation objects to analyze and manipulate code documentation. Includes classes for modules, classes, functions, variables, and external references.

class Doc:
    def __init__(self, name: str, module, obj, docstring: str = ''): ...
    def url(self, relative_to=None, link_prefix='', top_ancestor=False) -> str: ...

class Class(Doc):
    def mro(self, only_documented=False) -> List['Class']: ...
    def methods(self, include_inherited=True, sort=True) -> List['Function']: ...
    def class_variables(self, include_inherited=True, sort=True) -> List['Variable']: ...

class Function(Doc):
    def params(self, annotate=False, link=None) -> List[str]: ...
    def return_annotation(self, link=None) -> str: ...

Documentation Objects

Command Line Interface

Use pdoc3 from the command line to generate documentation, start development servers, and integrate with build systems.

def main(_args=None) -> None: ...

class _WebDoc(BaseHTTPRequestHandler):
    def do_GET(self): ...
    def do_HEAD(self): ...

Command Line Interface

HTML and Markdown Processing

Process docstrings and generate formatted output with support for multiple docstring formats, LaTeX math, syntax highlighting, and cross-linking.

def to_html(text, docformat=None, module=None, link=None, latex_math=False) -> str: ...
def to_markdown(text, docformat=None, module=None, link=None) -> str: ...
def minify_html(html: str) -> str: ...
def minify_css(css: str) -> str: ...
def glimpse(text: str, max_length=153, paragraph=True) -> str: ...

HTML and Markdown Processing

Global Configuration

# Template system
tpl_lookup: TemplateLookup  # Mako template lookup object

# Documentation override system  
__pdoc__: Dict[str, Union[bool, str]]  # Global documentation overrides

# Context management
class Context(dict):
    def __init__(self, *args, **kwargs): ...

# Version information
__version__: str  # Package version string

Common Error Handling

pdoc3 provides several mechanisms for handling errors during documentation generation:

  • skip_errors=True: Continue processing when encountering unimportable modules
  • Module.ImportWarning: Custom warning class for import issues
  • ReferenceWarning: Warning for unresolved cross-references
  • Template error handling: Detailed error reporting for template rendering issues

Types

from typing import Dict, List, Optional, Union, Callable, Any, Type, TypeVar
from types import ModuleType

# Type variables
T = TypeVar('T', 'Module', 'Class', 'Function', 'Variable')

# Function signatures
DocFilter = Callable[[Doc], bool]
LinkFunction = Callable[[Doc], str]

# Configuration types
TemplateConfig = Dict[str, Any]
DocMapping = Dict[str, Union[Module, Class, Function, Variable]]