pymarkdoc 0.1.0

Generate Markdown documentation from Python docstrings

pymarkdoc

Generate Markdown documentation from Python code.

A simple command line tool to produce a markdown document when given a python file, a directory, a local package, a global package, whatever.

This isn't a fully customisble documentation system. If you're looking for features and customisability checkout MkDocs. If you want something minimalist that can generate nice user facing HTML docs, try pdoc.

Installation

pymarkdoc is a command line utility. Installation is straightforward.

Using uv

If you use uv:

uv tool install pymarkdoc

Using pipx

Install with:

pipx install pymarkdoc

Basic Usage

# Output markdown to stdout
pymarkdoc <package>

# Output to a file
pymarkdoc -o <filename> <package>

# Include a table of contents
pymarkdoc --toc <package>

# Include package metadata in docs, i.e. version number
pymarkdoc --metadata <package>

# For example
pymarkdoc urllib3 > docs.md
pymarkdoc --metadata --toc --output /tmp/docs.md urllib3

Other Usage Examples

# Document an arbitrary python file
pymarkdoc /path/to/some/file.py

# Document an arbitrary directory path
pymarkdoc ~/source/myproject/

Command options

• --output, -o: Write documentation to a file instead of stdout.
• --toc / --no-toc: Toggle the table of contents.
• --metadata: Include package version and other metadata when available.
• --version, -v: Show program's version number and exit.

Writing Documentation Comments

Add doc comments as normal, or preferably in plain markdown as you would for pdoc.

You can include other markdown files in the final output using the include syntax:

"""
.. include:: ../README.md
"""

You can skip some lines of an included file with:

"""
.. include:: ../README.md
   :start-line: 5
"""

Cross-Environment Support

pymarkdoc can document packages from your current Python environment:

# These work even when pymarkdoc is isolated
pymarkdoc requests          # Documents requests from your current environment
pymarkdoc django           # Documents django from your current environment

pymarkdoc automatically detects and loads packages from:

• Active virtual environments (via VIRTUAL_ENV)
• System Python site-packages
• User site-packages

Handling Missing Dependencies

If the package you're documenting has missing dependencies, pymarkdoc will still generate documentation for the available API. Missing dependencies are automatically mocked, allowing documentation generation to continue:

# Works even if some dependencies aren't installed
pymarkdoc mypackage