docstring-to-markdown

What it is and what it does

docstring-to-markdown is a lightweight converter that transforms Python docstrings written in reStructuredText or Google format into Markdown. It's designed to run on demand, making it useful in documentation pipelines, code analysis tools, or any workflow that needs to normalize docstring formats. The package supports Python 3.7 and later, with tested coverage through Python 3.13.

The converter works by recognizing the input format and applying format-specific transformations—for example, converting RST math notation like `:math:\`\\sum\`` to Markdown's dollar-sign syntax `$\\sum$`. When the format is unrecognized, it raises UnknownFormatError. The package is designed to be extended: custom converters can be registered via entry points, and built-in converters can be overridden by providing matching entry points.

Use it for:

• Normalize docstrings across a codebase from RST to Markdown for consistent documentation rendering.
• Generate Markdown documentation from existing Python modules with reStructuredText docstrings.
• Integrate into documentation build tools (e.g., Sphinx plugins) to convert docstring formats on the fly.
• Support Google-style docstrings in projects that need Markdown output for API documentation.
• Build custom docstring processors by extending the converter via entry points for domain-specific formats.

Worth the install?

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

Converts Python docstrings from reStructuredText and Google format to Markdown on the fly, with extensibility via entry points for custom converters.

Yes, if you need to convert reStructuredText or Google-format docstrings to Markdown. The package is lightweight, has no security vulnerabilities, and integrates well into documentation workflows. The aging maintenance status (469 days since last release) is a minor concern for a stable, narrowly-scoped tool, but the repository remains active. The copyleft license (LGPL-2.1-or-later) is a consideration if you plan to redistribute or embed it in proprietary code.

Install

docstring-to-markdown on PyPI

pip install docstring-to-markdown

uv add docstring-to-markdown

poetry add docstring-to-markdown

Installing docstring-to-markdown

Before you install

Low friction install with minimal dependencies (importlib-metadata, typing_extensions). Maintenance status is aging—last release was 469 days ago, though the repository remains active with a recent commit on 2025-06-20.

License in practice

Licensed under LGPL-2.1-or-later (copyleft). Any derivative work or distribution must preserve the same license terms and make source available.

Quickstart

pip install docstring-to-markdown

import docstring_to_markdown
result = docstring_to_markdown.convert(':math:`\\sum`')
print(result)  # '$\\sum$'

Requires Python 3.7 or later; raises UnknownFormatError when docstring format cannot be recognized.

Verify before relying

• Extent of Google-format docstring support beyond 'initial' (v0.13 onward) and which Google-style features are actually handled.
• Performance characteristics when processing large batches of docstrings or very long docstrings.
• Completeness of reStructuredText feature coverage—which RST constructs convert successfully and which may fail or degrade.

Package facts

Evidence: docstring_to_markdown-0.17-py3-none-any.whl

Keywords: Docstring, conversion, markdown

Tags

More Markup packages