pdoc: API Documentation Generator

Warnings

• breaking pdoc is the actively maintained original project. `pdoc3` is an unrelated fork with different features, maintainers, and licenses, and is not recommended by the official `pdoc` project. Ensure you are installing and using `pdoc` from PyPI (`pip install pdoc`).
  Fix: Always install `pdoc` (not `pdoc3`) and refer to the official documentation at `pdoc.dev`.
• gotcha When `pdoc` imports your modules for documentation, any top-level executable code not protected by an `if __name__ == "__main__":` guard will run. This can cause unexpected side effects, errors (e.g., if code expects command-line arguments), or slow documentation generation.
  Fix: Encapsulate any module-level executable code within an `if __name__ == "__main__":` block to prevent it from running during import.
• gotcha The current `pdoc` library primarily generates output in HTML format. If you require other formats (like PDF or Markdown for integration with static site generators that expect raw Markdown), you may need to look for external tools or alternative documentation generators.
  Fix: Consider `pdoc` for HTML-centric documentation. For other formats, evaluate tools like Sphinx or pandoc for conversion after HTML generation, or choose a different primary documentation generator.
• gotcha For `pdoc` to recognize a directory as a package and document its submodules, the directory must contain an `__init__.py` file (even if empty), following standard Python package conventions. Simply having Python files in a directory without `__init__.py` will not allow `pdoc` to traverse and document it as a package.
  Fix: Ensure all directories intended to be documented as Python packages contain an `__init__.py` file.
• deprecated The `__pdoc__` module-level dictionary (used to override docstrings or control visibility of members) was explicitly removed in `pdoc` 1.0.0 (January 2021) as 'rarely required'. However, recent documentation (pdoc 16.0.0) indicates it is now supported again for specific use cases like `namedtuple` or including private objects. There's historical confusion on this, so verify usage with the latest official `pdoc.dev` documentation.
  Fix: Refer to the current `pdoc.dev` documentation for the up-to-date behavior of `__pdoc__`. If you're using an older `pdoc` version that removed it, you may need to upgrade or adjust your documentation practices.

Install

• pip install pdoc Install pdoc

Imports

• Module

  from pdoc import Module

  Main entry point for programmatic documentation generation.
• html

  from pdoc import html

  Function to render a module's documentation to HTML.
• text

  from pdoc import text

  Function to render a module's documentation to plain text.
• import_module

  from pdoc import import_module

  Helper to import arbitrary modules/files for documentation.

Quickstart

This quickstart demonstrates how to generate HTML documentation for a Python module programmatically using `pdoc.html()`. It creates a dummy module, generates its documentation, and saves it to an HTML file. The `pdoc` library is primarily used as a command-line tool, but offers a robust programmatic API. For CLI usage, simply run `pdoc your_module.py` or `pdoc your_package`.

import os
import sys
from pathlib import Path

# Create a dummy module for documentation
dummy_module_content = '''
"""A simple example module."""

class MyClass:
    """This is MyClass.

    Attributes:
        name (str): The name of the instance.
    """
    def __init__(self, name: str):
        self.name = name

    def greet(self, loud: bool = False) -> str:
        """Greets the user.

        Args:
            loud (bool): If True, returns an uppercase greeting.

        Returns:
            str: The greeting message.
        """
        message = f"Hello, {self.name}!"
        return message.upper() if loud else message

def my_function(x: int, y: int) -> int:
    """Adds two numbers.

    Args:
        x (int): The first number.
        y (int): The second number.

    Returns:
        int: The sum of x and y.
    """
    return x + y
'''

# Create a temporary file for the dummy module
module_path = Path('./temp_my_module.py')
module_path.write_text(dummy_module_content)

# Add the current directory to sys.path to allow importing the temporary module
sys.path.insert(0, str(Path('.').resolve()))

# Generate documentation programmatically
try:
    import temp_my_module
    from pdoc import html

    print("Generating documentation for temp_my_module...")
    # Generate HTML documentation for the module
    html_output = html(temp_my_module)

    # Optionally write to a file
    output_dir = Path('./pdoc_output')
    output_dir.mkdir(exist_ok=True)
    output_file = output_dir / 'temp_my_module.html'
    output_file.write_text(html_output)

    print(f"Documentation generated to {output_file.resolve()}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the temporary module file and sys.path
    if module_path.exists():
        module_path.unlink()
    if str(Path('.').resolve()) in sys.path:
        sys.path.remove(str(Path('.').resolve()))

# You can also run from the command line:
# pdoc ./temp_my_module.py
# or for a package:
# pdoc my_package --output-directory docs