npdoc2md

A CLI utility for autogenerating markdown documentation from numpy-style Python docstrings. Point it at a Python file or directory, and it produces clean markdown files suitable for use with MkDocs or any other markdown-based documentation system.

Installation

Python 3.10+ is required.

Install from source with pip:

git clone https://github.com/jwlodek/npdoc2md
cd npdoc2md
pip install .

Usage

usage: npdoc2md [-h] [--version] [--verbose] [--quiet] [--include-private]
                [--private-whitelist PRIVATE_WHITELIST [PRIVATE_WHITELIST ...]]
                input_path output_path

Utility for autogenerating markdown from numpy-style docstrings.

positional arguments:
  input_path            Path to the input file or directory containing files to parse
  output_path           Path to the output directory where markdown files will be saved

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --verbose, -v         Enable verbose logging
  --quiet, -q           Enable quiet mode (only errors will be logged)
  --include-private     Include private members (those starting with an underscore)
  --private-whitelist PRIVATE_WHITELIST [PRIVATE_WHITELIST ...]
                        List of private member names to include even without --include-private.

Basic example

Generate markdown for a single file:

npdoc2md src/npdoc2md/utils.py docs/

Generate markdown for an entire package (the directory is searched recursively for .py files):

npdoc2md src/npdoc2md/ docs/

If the output directory does not exist, npdoc2md will create it automatically.

Including private members

By default, private members (names starting with _) are excluded, with the exception of __init__. You can include all private members with:

npdoc2md --include-private src/mypackage/ docs/

Or whitelist specific private names:

npdoc2md --private-whitelist __init__ _my_helper src/mypackage/ docs/

Programmatic usage

You can also use npdoc2md as a library:

from pathlib import Path
from npdoc2md import npdoc2md

results = npdoc2md(Path("src/mypackage"), Path("docs/"))
for output_file, markdown_text in results.items():
    output_file.write_text(markdown_text)

Docstring guidelines

npdoc2md uses numpy-style docstrings. For best results:

• Use triple-quoted (""") docstrings for modules, classes, and functions.
• Follow numpy docstring conventions for Parameters, Returns, Raises, Attributes, and Examples sections.

Example output

The docs/ directory in this repository was generated by running npdoc2md on itself. For example, docs/utils.md was produced from src/npdoc2md/utils.py.

License

MIT License — Copyright (c) 2020-2026, Jakub Wlodek