HTML Rendering and Templates

def configure(
    *,
    docformat: Literal["markdown", "google", "numpy", "restructuredtext"] = "restructuredtext",
    include_undocumented: bool = True,
    edit_url_map: Mapping[str, str] | None = None,
    favicon: str | None = None,
    footer_text: str = "",
    logo: str | None = None,
    logo_link: str | None = None,
    math: bool = False,
    mermaid: bool = False,
    search: bool = True,
    show_source: bool = True,
    template_directory: Path | None = None
) -> None:
    """
    Configure global rendering options for HTML generation.
    
    Parameters:
    - docformat: Docstring format ("markdown", "restructuredtext", "google", "numpy")
    - include_undocumented: bool - Include members without docstrings
    - edit_url_map: Mapping[str, str] | None - Module name to URL prefix mapping for "Edit on GitHub" links
    - favicon: str | None - Path/URL for favicon image
    - footer_text: str - Additional text for navigation footer
    - logo: str | None - URL to project logo image
    - logo_link: str | None - URL the logo should link to
    - math: bool - Enable LaTeX math formula rendering via MathJax
    - mermaid: bool - Enable Mermaid diagram rendering
    - search: bool - Enable search functionality and index building
    - show_source: bool - Include "View Source" links in output
    - template_directory: Path | None - Custom template directory path
    
    Effects:
    - Sets global options for all subsequent rendering calls
    - Configures template engine and processing pipeline
    """

def html_module(module: doc.Module, all_modules: Mapping[str, doc.Module], mtime: str | None = None) -> str:
    """
    Render HTML documentation for a single module.
    
    Parameters:
    - module: doc.Module - Module documentation object to render
    - all_modules: Mapping[str, doc.Module] - All modules for cross-linking
    - mtime: str | None - Include live-reloading JavaScript if provided
    
    Returns:
    - str: Complete HTML document for the module
    
    Features:
    - Cross-module linking and navigation
    - Syntax highlighting for code examples
    - Responsive design with mobile support
    - Customizable via Jinja2 templates
    """

def html_index(all_modules: dict[str, doc.Module]) -> str:
    """
    Generate HTML index page for multiple modules.
    
    Parameters:
    - all_modules: dict[str, doc.Module] - All documented modules
    
    Returns:
    - str: HTML index page content
    
    Features:
    - Module hierarchy navigation
    - Search integration
    - Overview of all documented modules
    """

def html_error(
    error: Exception,
    traceback_str: str,
    module_name: str = ""
) -> str:
    """
    Generate HTML error page for documentation failures.
    
    Parameters:
    - error: Exception - The error that occurred
    - traceback_str: str - Full traceback information
    - module_name: str - Name of module that failed (if applicable)
    
    Returns:
    - str: HTML error page with debugging information
    """

def search_index(all_modules: dict[str, doc.Module]) -> str:
    """
    Generate JavaScript search index for client-side search.
    
    Parameters:
    - all_modules: dict[str, doc.Module] - All modules to index
    
    Returns:
    - str: JavaScript code containing search index data
    
    Features:
    - Full-text search of docstrings and signatures
    - Identifier-based search with autocomplete
    - Fast client-side search without server requests
    """

def repr_module(module: doc.Module) -> str:
    """
    Generate text representation of module for debugging.
    
    Parameters:
    - module: doc.Module - Module to represent
    
    Returns:
    - str: Text representation showing module structure
    """

from pdoc import render, doc

# Configure rendering
render.configure(
    docformat="google",
    show_source=True,
    math=True
)

# Generate HTML for module
module_obj = doc.Module.from_name("my_package")
all_modules = {"my_package": module_obj}

# Render individual module
html_content = render.html_module(module_obj, all_modules)

# Generate index page
index_html = render.html_index(all_modules)

from pdoc import render
from pathlib import Path

# Use custom templates
render.configure(
    template_directory="./custom_templates",
    show_source=False,
    math=True,
    mermaid=True,
    # Custom variables available in templates
    project_name="My Project",
    project_version="1.0.0"
)

from pdoc import render, doc
from pathlib import Path

# Load multiple related modules
modules = {}
module_names = ["core", "utils", "plugins"]

for name in module_names:
    modules[name] = doc.Module.from_name(f"my_project.{name}")

# Configure for production
render.configure(
    docformat="numpy",
    show_source=True,
    math=True,
    mermaid=True
)

# Generate all HTML files
output_dir = Path("./docs")
output_dir.mkdir(exist_ok=True)

# Render each module
for module_name, module_obj in modules.items():
    html = render.html_module(module_obj, modules)
    (output_dir / f"{module_name}.html").write_text(html)

# Generate index and search
index_html = render.html_index(modules)
(output_dir / "index.html").write_text(index_html)

search_js = render.search_index(modules)
(output_dir / "search.js").write_text(search_js)

from pdoc import render, doc
import traceback

def safe_render_module(module_name: str) -> str:
    """Safely render module with error handling"""
    try:
        module_obj = doc.Module.from_name(module_name)
        return render.html_module(module_obj, {module_name: module_obj})
    except Exception as e:
        # Generate error page
        tb = traceback.format_exc()
        return render.html_error(e, tb, module_name)

# Usage
html_output = safe_render_module("potentially_problematic_module")

from pdoc import render

# Comprehensive configuration
render.configure(
    # Docstring processing
    docformat="restructuredtext",
    
    # Source code integration
    show_source=True,
    
    # Enhanced features
    math=True,           # LaTeX math rendering
    mermaid=True,        # Diagram support
    
    # Template customization
    template_directory="./templates",
    
    # Custom CSS and styling
    custom_css="body { font-family: 'Helvetica'; }",
    
    # Logo and branding
    logo_url="https://example.com/logo.png",
    project_name="My API Documentation",
    
    # Navigation options
    sort_identifiers=True,
    show_inherited_members=True
)

from pdoc import render

def configure_for_development():
    """Configure for development with debugging features"""
    render.configure(
        docformat="markdown",
        show_source=True,
        math=False,
        mermaid=False,
        # Show all internal details
        show_private_members=True
    )

def configure_for_production():
    """Configure for production with optimized output"""
    render.configure(
        docformat="google",
        show_source=False,
        math=True,
        mermaid=True,
        # Clean public API only
        show_private_members=False,
        minify_html=True
    )

# Directory structure for custom templates:
# templates/
# ├── module.html.jinja2      # Main module template
# ├── index.html.jinja2       # Index page template
# ├── frame.html.jinja2       # HTML frame/layout
# └── resources/
#     ├── theme.css           # Custom CSS
#     └── custom.js           # Custom JavaScript

from pdoc import render

render.configure(template_directory="./templates")