{"id":2660,"library":"pdoc","title":"pdoc: API Documentation Generator","description":"pdoc is a Python package for generating API documentation that follows your project's Python module hierarchy. It extracts documentation from docstrings, supports Markdown, type annotations, and various docstring formats (NumPy, Google-style). It can generate standalone HTML files or serve documentation via a built-in live-reloading web server, focusing on simplicity and minimal configuration. It is actively maintained by the mitmproxy team.","status":"active","version":"16.0.0","language":"en","source_language":"en","source_url":"https://github.com/mitmproxy/pdoc/","tags":["documentation","api documentation","static site generator","markdown","type annotations"],"install":[{"cmd":"pip install pdoc","lang":"bash","label":"Install pdoc"}],"dependencies":[],"imports":[{"note":"Main entry point for programmatic documentation generation.","symbol":"Module","correct":"from pdoc import Module"},{"note":"Function to render a module's documentation to HTML.","symbol":"html","correct":"from pdoc import html"},{"note":"Function to render a module's documentation to plain text.","symbol":"text","correct":"from pdoc import text"},{"note":"Helper to import arbitrary modules/files for documentation.","symbol":"import_module","correct":"from pdoc import import_module"}],"quickstart":{"code":"import os\nimport sys\nfrom pathlib import Path\n\n# Create a dummy module for documentation\ndummy_module_content = '''\n\"\"\"A simple example module.\"\"\"\n\nclass MyClass:\n    \"\"\"This is MyClass.\n\n    Attributes:\n        name (str): The name of the instance.\n    \"\"\"\n    def __init__(self, name: str):\n        self.name = name\n\n    def greet(self, loud: bool = False) -> str:\n        \"\"\"Greets the user.\n\n        Args:\n            loud (bool): If True, returns an uppercase greeting.\n\n        Returns:\n            str: The greeting message.\n        \"\"\"\n        message = f\"Hello, {self.name}!\"\n        return message.upper() if loud else message\n\ndef my_function(x: int, y: int) -> int:\n    \"\"\"Adds two numbers.\n\n    Args:\n        x (int): The first number.\n        y (int): The second number.\n\n    Returns:\n        int: The sum of x and y.\n    \"\"\"\n    return x + y\n'''\n\n# Create a temporary file for the dummy module\nmodule_path = Path('./temp_my_module.py')\nmodule_path.write_text(dummy_module_content)\n\n# Add the current directory to sys.path to allow importing the temporary module\nsys.path.insert(0, str(Path('.').resolve()))\n\n# Generate documentation programmatically\ntry:\n    import temp_my_module\n    from pdoc import html\n\n    print(\"Generating documentation for temp_my_module...\")\n    # Generate HTML documentation for the module\n    html_output = html(temp_my_module)\n\n    # Optionally write to a file\n    output_dir = Path('./pdoc_output')\n    output_dir.mkdir(exist_ok=True)\n    output_file = output_dir / 'temp_my_module.html'\n    output_file.write_text(html_output)\n\n    print(f\"Documentation generated to {output_file.resolve()}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the temporary module file and sys.path\n    if module_path.exists():\n        module_path.unlink()\n    if str(Path('.').resolve()) in sys.path:\n        sys.path.remove(str(Path('.').resolve()))\n\n# You can also run from the command line:\n# pdoc ./temp_my_module.py\n# or for a package:\n# pdoc my_package --output-directory docs","lang":"python","description":"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`."},"warnings":[{"fix":"Always install `pdoc` (not `pdoc3`) and refer to the official documentation at `pdoc.dev`.","message":"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`).","severity":"breaking","affected_versions":"All versions (comparison between projects)"},{"fix":"Encapsulate any module-level executable code within an `if __name__ == \"__main__\":` block to prevent it from running during import.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All current versions"},{"fix":"Ensure all directories intended to be documented as Python packages contain an `__init__.py` file.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Versions 1.0.0 to ~15.x.x (exact re-introduction version unclear), potentially confusing for users migrating from older versions or `pdoc3`."}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}