{"id":9214,"library":"pydoctor","title":"Pydoctor","description":"Pydoctor is a standalone API documentation generator that works by static analysis. It was primarily written to replace epydoc for the Twisted project, especially due to epydoc's difficulties with `zope.interface`. It aims to provide comprehensive API documentation for Python projects, supporting various docstring formats like epytext, reStructuredText, Google, and Numpy styles. The current version is 25.10.1 and it is actively maintained.","status":"active","version":"25.10.1","language":"en","source_language":"en","source_url":"https://github.com/twisted/pydoctor","tags":["documentation","API","static analysis","doc generator","Python"],"install":[{"cmd":"pip install pydoctor","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or higher.","package":"Python","optional":false}],"imports":[],"quickstart":{"code":"# 1. Create a dummy Python package/module\nmkdir -p my_project/src/my_lib\necho \"\"\"\"\"\"A simple library.\"\"\"\"\" > my_project/src/my_lib/__init__.py\necho \"\"\"\"\"\"A simple module.\ndef greet(name: str) -> str:\n    \"\"\"Greets the given name.\n\n    :param name: The name to greet.\n    :type name: str\n    :return: A greeting message.\n    :rtype: str\n    \"\"\"\n    return f'Hello, {name}!'\n\"\"\" > my_project/src/my_lib/greeting.py\n\n# 2. Run pydoctor to generate documentation\ncd my_project\npydoctor --project-name=\"My Project API\" \\\n         --project-version=\"1.0.0\" \\\n         --html-output=docs/api \\\n         src/my_lib\n\n# 3. View the generated documentation (e.g., open docs/api/index.html)","lang":"bash","description":"Pydoctor is primarily a command-line interface (CLI) tool. This quickstart demonstrates how to create a minimal Python project and generate its API documentation using the `pydoctor` command-line utility. The `--html-output` option specifies the output directory, and the positional arguments are the paths to the Python source to be documented."},"warnings":[{"fix":"Ensure your Python environment meets the minimum `requires_python` version specified on PyPI (currently >=3.9 for 25.10.1).","message":"Pydoctor regularly drops support for older Python versions. For example, pydoctor 24.11 dropped Python 3.7, and pydoctor 25.4 dropped Python 3.8. Always check the `requires_python` metadata for compatibility.","severity":"breaking","affected_versions":">=24.11"},{"fix":"Configure `--html-viewsource-base` with a static reference, such as `https://github.com/your-org/your-repo/tree/v1.2.3` or `https://github.com/your-org/your-repo/tree/COMMIT_SHA`.","message":"The `--html-viewsource-base` argument, used for linking to source code, should point to a stable Git tag or commit SHA, not a mutable branch (e.g., `master`/`main`). Using a branch can lead to broken source links due to line number mismatches as the code evolves.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Instead of `--html-write-function-pages`, utilize the generated Intersphinx inventory (`objects.inv`) for deep-linking to specific functions or methods in your documentation.","message":"The `--html-write-function-pages` option, which generated individual HTML files for functions and methods, was removed in pydoctor 21.2.0.","severity":"breaking","affected_versions":">=21.2.0"},{"fix":"Interpret exit codes carefully in CI/CD pipelines. A non-zero exit code doesn't always mean a critical failure of documentation generation, but may indicate docstring quality issues. Use `--warnings-as-errors` if strict docstring formatting is required.","message":"Pydoctor's exit codes can be non-zero even if HTML output is successfully generated. Exit code `1` indicates a crash, `2` for malformatted docstrings, and `3` if warnings are treated as errors via `--warnings-as-errors`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Enable verbose logging with `-v` (or multiple `-vvv`) to get more details. Check for issues in the source code or docstring parsing. Consult the full traceback for the specific error location.","cause":"A runtime error occurred during static analysis or HTML generation. This corresponds to pydoctor's exit code 1.","error":"Pydoctor crashed with traceback"},{"fix":"Upgrade pydoctor to version 25.4.0 or newer to support implicit native namespace packages (PEP 420). Alternatively, ensure that the source directories being documented are valid Python packages with an `__init__.py` file, or explicitly configure them.","cause":"Prior to pydoctor 25.4.0, pydoctor expected source directories to be traditional packages with an `__init__.py` file. It did not fully support implicit native namespace packages (PEP 420).","error":"Error: Source directory lacks __init__.py"},{"fix":"Verify the path provided to the `--template-dir` option (or its equivalent in a config file) is correct and points to an existing directory containing valid template files.","cause":"Pydoctor could not find the specified custom template directory, or the path provided was not a directory.","error":"Error 'Template folder do not exist or is not a directory'"},{"fix":"Specify the project's base directory using `--project-base-dir` for accurate source link computation. Use `--add-package` or `--add-module` explicitly, and ensure all relevant source code is discoverable. For module/package name collisions, better messages are triggered in newer versions.","cause":"Pydoctor's static analysis might struggle with complex import structures, aliasing, or the project's base directory not matching the current working directory.","error":"Pydoctor fails to find Python objects or resolve links correctly."}]}