{"id":7557,"library":"pydoc-markdown","title":"Pydoc-Markdown","description":"Pydoc-Markdown is a tool that generates Python API documentation in Markdown format by parsing Python code using the `docspec` library. It supports multiple documentation styles, including Sphinx, Google, and its own specific format. While the project is still actively maintained with recent releases, the maintainer suggests considering `mkdocstrings` for new projects due to limited time for proper maintenance and development. The current stable version is 4.8.2.","status":"maintenance","version":"4.8.2","language":"en","source_language":"en","source_url":"https://github.com/NiklasRosenstein/pydoc-markdown","tags":["documentation","markdown","api-documentation","docstrings","cli","mkdocs"],"install":[{"cmd":"pip install pydoc-markdown","lang":"bash","label":"Install with pip"},{"cmd":"pipx install pydoc-markdown","lang":"bash","label":"Install with pipx (recommended for isolation)"}],"dependencies":[{"reason":"Core library for parsing Python API objects.","package":"docspec"},{"reason":"Parses various docstring formats (Sphinx, Google, etc.).","package":"docstring-parser"},{"reason":"Required for YAML configuration files.","package":"pyyaml"},{"reason":"Used for configuration (known to cause compatibility issues with older versions).","package":"databind.core"}],"imports":[{"note":"Pydoc-Markdown is primarily used via its command-line interface. Direct programmatic imports for generation are less common for end-users, focusing instead on configuration files.","symbol":"pydoc_markdown","correct":"Via command-line: pydoc-markdown"}],"quickstart":{"code":"mkdir my_project\ncd my_project\n\n# Create a sample Python module\ncat << EOF > my_module.py\n\"\"\"A simple example module.\"\"\"\n\ndef greet(name: str) -> str:\n    \"\"\"Greets a person by name.\n\n    :param name: The name of the person to greet.\n    :returns: A greeting string.\n    \"\"\"\n    return f\"Hello, {name}!\"\n\nclass MyClass:\n    \"\"\"A sample class.\n\n    :ivar value: An example instance variable.\n    \"\"\"\n    def __init__(self, value: int):\n        self.value = value\n\n    def get_value(self) -> int:\n        \"\"\"Returns the stored value.\"\"\"\n        return self.value\nEOF\n\n# Create a pydoc-markdown.yml configuration file\ncat << EOF > pydoc-markdown.yml\nloaders:\n  - type: python\n    search_path: [.]\nrenderer:\n  type: markdown\n  pages:\n    - title: My API\n      contents:\n        - 'my_module'\nEOF\n\n# Generate the documentation\npydoc-markdown --config pydoc-markdown.yml > API.md\n\n# To view the generated Markdown (optional)\n# cat API.md","lang":"bash","description":"This quickstart demonstrates how to generate Markdown API documentation for a simple Python module. It involves creating a Python file, defining a `pydoc-markdown.yml` configuration to specify the module and output, and then running the `pydoc-markdown` CLI command. The output is redirected to `API.md`."},"warnings":[{"fix":"Evaluate `mkdocstrings` as an alternative, especially for new projects or if long-term active development and extensive community support are critical.","message":"The project maintainer recommends considering `mkdocstrings` for new projects due to limited time for proper maintenance and development, despite continued updates.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project uses Python 3.8 or newer when installing and running Pydoc-Markdown.","message":"Python 3.7 compatibility was dropped in a recent version.","severity":"breaking","affected_versions":"4.8.2 and newer"},{"fix":"If using versions between 4.6.0 and 4.7.0, consider migrating to Novella or upgrading to 4.7.0+ to safely use YAML configuration. For 4.7.0 and later, YAML configuration is fully supported again.","message":"The 'old style' YAML/PyProject configuration was deprecated in versions around 4.6.0 in favor of Novella integration, but was then 'undeprecated' in 4.7.0 due to user preference.","severity":"deprecated","affected_versions":"4.6.0 (deprecated), 4.7.0+ (undeprecated)"},{"fix":"Upgrade Pydoc-Markdown to its latest version, which often includes updates to `databind` dependencies to fix such issues. For example, 4.8.1 upgraded to `^4.4.0` to fix a `ForwardRef` error.","message":"Compatibility issues with `databind` versions can lead to `ForwardRef` errors or `NoMatchingConverter` errors during configuration parsing.","severity":"gotcha","affected_versions":"Specific versions, notably when `databind` is >=4.5"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade Pydoc-Markdown to the latest version (e.g., `pip install --upgrade pydoc-markdown`). Version 4.8.1 specifically addressed a `NoMatchingConverter` error by upgrading `databind` and adjusting internal type definitions.","cause":"Mismatch or incompatibility with the `databind` dependency, particularly in how it handles generic types or recursive type definitions used internally by Pydoc-Markdown.","error":"NoMatchingConverter for TypeHint(typing.List[~T_Page])"},{"fix":"Ensure the `search_path` in your `pydoc-markdown.yml` includes the directory containing your module (e.g., `search_path: [.]` for the current directory, or `search_path: ['../src']` if modules are in `src/`). Alternatively, set the `PYTHONPATH` environment variable before running `pydoc-markdown`.","cause":"Pydoc-Markdown cannot find the Python module(s) specified in your configuration. This often happens if the `search_path` in `pydoc-markdown.yml` is incorrect or the module is not in `PYTHONPATH`.","error":"ModuleNotFoundError: No module named 'your_module_name'"},{"fix":"While specific fixes depend on the vulnerability, a general approach is to ensure Pydoc-Markdown and its dependencies are on the latest versions. For long-term projects, consider migrating to `mkdocstrings` as recommended by the maintainer.","cause":"This is a broader community concern regarding the project's long-term maintenance status, as noted by its maintainer, leading to potential security vulnerabilities from unpatched transitive dependencies.","error":"Pydoc-markdown is unmaintained (last supported Python version is 3.11, never left alpha stage). The author recommends switching to mkdocstrings. This causes: Security alerts from outdated transitive dependencies (e.g. Black parser)"}]}