pymarkdoc 0.1.0
Generate Markdown documentation from Python docstrings
License: MIT
Requires Python: >=3.10
Keywords: docstrings, documentation, generator, markdown

# pymarkdoc

[![PyPI - Version](https://img.shields.io/pypi/v/pymarkdoc.svg)](https://pypi.org/project/pymarkdoc)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pymarkdoc.svg)](https://pypi.org/project/pymarkdoc)
[![License](https://img.shields.io/pypi/l/pymarkdoc.svg)](https://git.sr.ht/~gk/pymarkdoc/blob/main/LICENSE)

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](https://www.mkdocs.org/). If you want something minimalist that can generate nice user facing HTML docs, try [pdoc](https://pdoc.dev/).

## Installation

`pymarkdoc` is a command line utility. Installation is straightforward.

### Using [uv](https://docs.astral.sh/uv/)

If you use `uv`:

```bash
uv tool install pymarkdoc
```

### Using [pipx](https://pipx.pypa.io/)

Install with:

```bash
pipx install pymarkdoc
```

## Basic Usage

```bash
# 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
```bash

# 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](https://pdoc.dev/).

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

```python
"""
.. include:: ../README.md
"""
```

You can skip some lines of an included file with:

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

### Cross-Environment Support

`pymarkdoc` can document packages from your current Python environment:

```bash
# 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:

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