Pydoc-Markdown

4.8.2 · maintenance · verified Thu Apr 16

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.

Common errors

```
NoMatchingConverter for TypeHint(typing.List[~T_Page])
```
cause Mismatch or incompatibility with the `databind` dependency, particularly in how it handles generic types or recursive type definitions used internally by Pydoc-Markdown.

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.
```
ModuleNotFoundError: No module named 'your_module_name'
```
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`.

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`.
```
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)
```
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.

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.

Warnings

gotcha The project maintainer recommends considering `mkdocstrings` for new projects due to limited time for proper maintenance and development, despite continued updates.
Fix: Evaluate `mkdocstrings` as an alternative, especially for new projects or if long-term active development and extensive community support are critical.
breaking Python 3.7 compatibility was dropped in a recent version.
Fix: Ensure your project uses Python 3.8 or newer when installing and running Pydoc-Markdown.
deprecated 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.
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.
gotcha Compatibility issues with `databind` versions can lead to `ForwardRef` errors or `NoMatchingConverter` errors during configuration parsing.
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.

Install

pip install pydoc-markdown Install with pip
pipx install pydoc-markdown Install with pipx (recommended for isolation)

Imports

pydoc_markdown
```
Via command-line: pydoc-markdown
```
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.

Quickstart

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`.

mkdir my_project
cd my_project

# Create a sample Python module
cat << EOF > my_module.py
"""A simple example module."""

def greet(name: str) -> str:
    """Greets a person by name.

    :param name: The name of the person to greet.
    :returns: A greeting string.
    """
    return f"Hello, {name}!"

class MyClass:
    """A sample class.

    :ivar value: An example instance variable.
    """
    def __init__(self, value: int):
        self.value = value

    def get_value(self) -> int:
        """Returns the stored value."""
        return self.value
EOF

# Create a pydoc-markdown.yml configuration file
cat << EOF > pydoc-markdown.yml
loaders:
  - type: python
    search_path: [.]
renderer:
  type: markdown
  pages:
    - title: My API
      contents:
        - 'my_module'
EOF

# Generate the documentation
pydoc-markdown --config pydoc-markdown.yml > API.md

# To view the generated Markdown (optional)
# cat API.md

view raw JSON →