---
id: pydoc-markdown
version: "4.8.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# pydoc-markdown — Create Python API documentation in Markdown format.

License: permissive · Maintenance: active · Downloads: 245.3K/mo

## What it is and what it does

Pydoc-Markdown is a command-line tool that reads Python source code and generates Markdown-formatted API documentation without executing the code. It parses docstrings in multiple styles (Sphinx, Google, Pydoc-Markdown) and converts them to properly formatted Markdown, making it useful for teams that want to keep API docs in version control alongside their source.

The tool supports configuration via YAML or pyproject.toml files and can integrate with static site generators like MkDocs and Hugo, either directly or through the Novella build backend. It understands variable docstrings through special comment syntax and generates cross-references between API objects. With 14 runtime dependencies including Jinja2, click, and docspec, it provides a complete pipeline from Python source to publishable documentation.

Use it for:

- Generate API reference documentation for a Python library and commit it to version control alongside source code.
- Integrate API documentation generation into a MkDocs or Hugo site build using Novella.
- Convert existing docstrings in Sphinx or Google style to Markdown for a new documentation site.
- Document variable assignments and module-level constants using docspec comment syntax.
- Create a CI/CD step that regenerates and validates API docs on every commit.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Pydoc-Markdown parses Python source code and generates API documentation in Markdown format, supporting multiple docstring styles and integrating with static site generators.

Yes, if you need Markdown-based API documentation for Python projects. The tool is actively maintained, has no known vulnerabilities, and low install friction. Verify that the configuration style you plan to use (YAML, pyproject.toml, or Novella) is stable for your workflow before committing to it.

## Install

pip install pydoc-markdown
uv add pydoc-markdown
poetry add pydoc-markdown

## Installing pydoc-markdown

Before you install: Low install friction with a pure-Python wheel distribution. Active maintenance with recent commits; the project remains functional and under active development.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely provided you include the original license notice.

Quickstart:

pip install pydoc-markdown
pydoc-markdown --help
# Or: pipx install pydoc-markdown

Requires Python 3.7 or later; the package you document can target any Python version.

Verify before relying:

- Whether the YAML and pyproject.toml configuration formats are equally maintained after the shift toward Novella integration.
- Current state of Novella integration stability and whether it is production-ready for existing workflows.
- Performance characteristics when documenting large codebases with many modules and classes.
- Time since latest release and implications for stability in production use.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 245.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python api documentation generator, markdown documentation from docstrings, python code to markdown docs, docstring parser markdown, api docs markdown format, python documentation tool, generate markdown from python, api-docs, markdown-generation, static-site-integration

[View on SkillFed](https://skillfed.io/packages/pydoc-markdown) · [View on PyPI](https://pypi.org/project/pydoc-markdown/)