{"id":5363,"library":"pdoc3","title":"pdoc3","description":"pdoc3 is a Python library and command-line tool that automatically generates API documentation from your Python project's docstrings and type annotations. It supports various docstring formats like Markdown, numpydoc, and Google-style, and can output documentation in HTML or PDF formats. As an actively maintained fork of the original `pdoc` project, it focuses on Python 3+ compatibility and ease of use, aiming to provide sensible documentation with minimal configuration.","status":"active","version":"0.11.6","language":"python","source_language":"en","source_url":"https://github.com/pdoc3/pdoc/","tags":["documentation","api-generation","docstrings","python3","html","pdf"],"install":[{"cmd":"pip install pdoc3","lang":"bash","label":"Install pdoc3"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"Python","optional":false}],"imports":[{"note":"The PyPI package is 'pdoc3', but the primary module for programmatic use is named 'pdoc'.","wrong":"import pdoc3","symbol":"pdoc","correct":"import pdoc"}],"quickstart":{"code":"import pdoc\nimport os\n\n# Create a dummy module file for documentation\ndummy_module_content = \"\"\"\n\\\"\\\"\\\"\nA simple example module.\n\\\"\\\"\\\"\n\nclass MyClass:\n    \\\"\\\"\\\"\n    A sample class.\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) -> str:\n        \\\"\\\"\\\"\n        Greets the user.\n        \\\"\\\"\\\"\n        return f\"Hello, {self.name}!\"\n\ndef my_function(value: int) -> int:\n    \\\"\\\"\\\"\n    A sample function.\n\n    Args:\n        value (int): An integer input.\n\n    Returns:\n        int: The input value multiplied by 2.\n    \\\"\\\"\\\"\n    return value * 2\n\"\"\"\nwith open(\"my_example_module.py\", \"w\") as f:\n    f.write(dummy_module_content)\n\n# Generate documentation for the module\n# Output to a 'docs' directory\npdoc.pdoc(\"my_example_module\", output_directory=\"docs\")\n\nprint(\"Documentation generated in 'docs/' directory.\")\nprint(\"You can view it by opening docs/my_example_module.html\")\n\n# Clean up the dummy module file\nos.remove(\"my_example_module.py\")\n# To clean up the generated documentation directory:\n# import shutil\n# shutil.rmtree(\"docs\")","lang":"python","description":"This quickstart demonstrates how to generate HTML documentation for a simple Python module using pdoc3 programmatically. It creates a temporary Python file, generates docs into a 'docs/' directory, and then cleans up the temporary file. For command-line usage, simply run `pdoc your_module_or_package`."},"warnings":[{"fix":"Ensure your project runs on Python 3.9+ and use `pdoc3`. If targeting older Python versions, consider the legacy `pdoc` releases or other documentation tools.","message":"pdoc3 is a fork of the original `pdoc` and is exclusively for Python 3.9+. Older Python 2 or earlier Python 3 projects will not be compatible. The `0.5.0` release marked a major refactoring for Python 3 compatibility.","severity":"breaking","affected_versions":"<0.5.0 (pdoc compatibility)"},{"fix":"Always refer to the official `pdoc3` documentation for current features. If migrating, check for feature parity or changes.","message":"The `pdoc` and `pdoc3` projects have diverged. Features like the `__pdoc__` module-level dictionary (used to override or exclude docstrings) are supported in `pdoc3` but were removed from the original `pdoc` in its 1.0.0 release. Consult the correct project's documentation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the directory containing your module/package is in your `PYTHONPATH` environment variable or run `pdoc` from the parent directory of your module/package.","message":"Users frequently encounter `ValueError: File or module not found` or `ImportError` if the Python modules or packages to be documented are not correctly discoverable in the Python path (`PYTHONPATH`) or current working directory.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust documentation expectations; class-level docstrings should now include `__init__` documentation. If you relied on separate `__init__` documentation, you may need to refactor docstrings.","message":"Since version `0.6.0`, `__init__` methods are no longer documented separately. Their docstrings are merged into the class docstring, and constructor parameters are displayed on the class definition line, aligning with Sphinx/Python stdlib documentation conventions.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Upgrade to `pdoc3` version `0.11.2` or newer to ensure `--skip-errors` works reliably. Alternatively, ensure all modules are error-free.","message":"The `--skip-errors` flag might not function as expected in `pdoc3` versions prior to `0.11.2`, leading to documentation generation failures even when errors should be skipped.","severity":"gotcha","affected_versions":"<0.11.2"}],"env_vars":null,"search_vec":"'3':61 'activ':49 'aim':67 'annot':25 'api':15,77 'api-gener':76 'automat':13 'command':9 'command-lin':8 'compat':62 'configur':74 'docstr':22,29,79 'document':16,41,71,75 'eas':64 'focus':58 'fork':51 'format':30,46 'generat':14,78 'googl':36 'google-styl':35 'html':43,81 'librari':6 'like':31 'line':10 'maintain':50 'markdown':32 'minim':73 'numpydoc':33 'origin':54 'output':40 'pdf':45,82 'pdoc':55 'pdoc3':1,2 'project':20,56 'provid':69 'python':5,19,60 'python3':80 'sensibl':70 'style':37 'support':27 'tool':11 'type':24 'use':66 'various':28","created_at":"2026-04-14T01:30:37.169371+00:00","updated_at":"2026-04-16T17:57:30.063407+00:00","problems":[{"fix":"Run `pdoc3` using `python -m pdoc your_module` or ensure that your Python scripts directory (e.g., `~/.local/bin` or `C:\\PythonXX\\Scripts`) is added to your system's PATH.","cause":"The `pdoc` executable, installed by `pip install pdoc3`, is not found in your system's PATH environment variable.","error":"bash: pdoc: command not found"},{"fix":"Navigate to the parent directory of the module/package you wish to document and run `pdoc3 your_module_name` or add the relevant directory to your `PYTHONPATH` environment variable.","cause":"pdoc3 cannot find the specified Python module or package because it's not in Python's import path (sys.path) or the current working directory is not the parent of the module/package.","error":"ModuleNotFoundError: No module named 'your_module'"},{"fix":"Ensure the module or file path is correct, the module is installable/importable from the environment where pdoc3 is run, and that packages have proper `__init__.py` files if they are not implicit namespace packages. Consider running `pdoc3 --html .` from your project's root for easier discovery.","cause":"pdoc3 failed to locate the specified Python file or module, often due to an incorrect path, an uninstalled package, or a missing `__init__.py` in a directory when trying to document a package.","error":"ValueError: File or module 'xxx' not found"},{"fix":"Downgrade Jinja2 to a compatible version (e.g., `pip install 'Jinja2<3.1'`) or upgrade pdoc3 to its latest version, which might have updated its Jinja2 dependency handling (`pip install --upgrade pdoc3`).","cause":"This error occurs due to an incompatibility between your installed pdoc3 version and a newer version of the Jinja2 templating engine, as Jinja2 moved or removed the `escape` import in recent updates.","error":"ImportError: cannot import name 'escape' from 'jinja2'"},{"fix":"For programmatic usage with pdoc3, you generally work with `pdoc.Module` objects and then call methods like `pdoc.html()` or `pdoc.text()` on them. The standard command-line usage `pdoc3 <module_name>` is usually sufficient.","cause":"This typically happens when attempting to use programmatic APIs (`pdoc.pdoc(...)`) intended for the older `pdoc` library, while `pdoc3` is installed, which has a different programmatic interface.","error":"AttributeError: module 'pdoc' has no attribute 'pdoc'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.11.6","cli_name":"pdoc3","cli_version":"pdoc3 0.11.6","type":"library","homepage":"https://pdoc3.github.io/pdoc/","github":"https://github.com/pdoc3/pdoc","docs":"https://pdoc3.github.io/pdoc/doc/pdoc/","changelog":null,"pypi":"https://pypi.org/project/pdoc3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}