haystack-pydoc-tools

What it is and what it does

haystack-pydoc-tools is a command-line tool that reads YAML configuration files describing Python modules and generates Docusaurus-compatible Markdown API reference documentation. It uses griffe to parse Python source code and extract docstrings, then griffe2md to render them as structured Markdown suitable for documentation sites. The tool supports both single-file and batch processing (with parallel execution) and includes a legacy compatibility mode for older pydoc-markdown configurations.

The package is designed for teams building documentation sites with Docusaurus who want to keep API docs in sync with source code. Configuration is minimal: you specify search paths, module names, and output metadata (title, description, filename), and the tool handles the rest. It supports filtering (documented-only mode, empty-module skipping) and can be integrated into CI/CD pipelines to regenerate docs on each release.

Use it for:

• Auto-generate API reference docs for a Python library and commit them to your Docusaurus site
• Batch-process multiple Python packages into separate Markdown files for a unified documentation portal
• Migrate from pydoc-markdown to a modern griffe-based workflow while keeping existing YAML configs
• Keep API documentation in sync with source code by running the tool in CI on each commit
• Generate Markdown API docs for internal tools without manually writing docstring-to-docs converters

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates Docusaurus-compatible Markdown API documentation from Python source code by parsing docstrings with griffe and rendering them via griffe2md.

Yes. The package solves a real problem—converting Python docstrings to Docusaurus-ready Markdown—with low install friction, active maintenance, no known vulnerabilities, and a permissive license. It's suitable for projects that already use Docusaurus and want automated API doc generation. The YAML-based configuration is straightforward, and parallel processing supports larger codebases. Install if you maintain a Docusaurus site and want to automate API reference generation.

Install

haystack-pydoc-tools on PyPI

pip install haystack-pydoc-tools

uv add haystack-pydoc-tools

poetry add haystack-pydoc-tools

Installing haystack-pydoc-tools

Before you install

Low friction: pure Python wheel with four straightforward runtime dependencies (black, griffe, griffe2md, pyyaml). Active maintenance status with recent releases.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

pip install haystack-pydoc-tools

# Create config.yml with loaders and renderer sections
loaders:
  - search_path: [src]
    modules:
      - my_module
renderer:
  title: My API
  filename: api.md

# Run from command line
haystack-pydoc config.yml output/

Requires Python 3.10 or later; griffe must be able to parse the target Python modules.

Verify before relying

• Whether the tool handles complex type hints, generics, and modern Python syntax correctly
• Performance characteristics when processing large codebases or many modules in parallel
• Compatibility with different Docusaurus versions and markdown rendering edge cases

Package facts

Evidence: haystack_pydoc_tools-0.7.0-py3-none-any.whl

Tags

More Documentation packages