Tired of Complex Documentation Tools? Generate Markdown Docs from Python Docstrings in Seconds!

Is your Python project suffering from a lack of clear, concise documentation? Are you overwhelmed by heavy-duty tools like MkDocs and ReadTheDocs? Then you need python-docstring-markdown, the simple, yet powerful tool that generates beautiful Markdown documentation directly from your Python docstrings.

Why Choose python-docstring-markdown? The Benefits are Clear

Unlike bloated documentation generators, python-docstring-markdown focuses on simplicity and ease of use. Get up and running in minutes and finally document your code effectively using intelligently parsed Python docstrings.

• Lightweight and Fast: Perfect for small to medium-sized Python projects where complex documentation systems are overkill. Quickly generate documentation and get back to coding.
• Easy Setup: Install with a single pip command and start generating documentation immediately.
• Markdown Output: Creates clean, readable Markdown files that integrate seamlessly with GitHub and other platforms.
• Automatic Table of Contents: Navigating your documentation is a breeze with auto-generated table of contents and anchor links.
• Preserves Module Hierarchy: Your documentation mirrors the structure of your project, making it easy to understand the relationships between modules, classes, and functions.
• Understands Your Style: Automatically detects ReST, Google, Numpydoc, and Epydoc docstring styles for accurate parsing.
• Handles Complex Structures: Effortlessly documents nested classes and functions, ensuring comprehensive coverage.
• Tracks Exports: Automatically documents module exports defined in __all__. This keeps track of exactly what is intended to be exposed by your module.

Installation: Get Started in Seconds

Installing python-docstring-markdown is as easy as:

pip install python-docstring-markdown

That's it! You're ready to start generating documentation.

Usage: Two Simple Ways to Generate Documentation

python-docstring-markdown offers both a command-line interface (CLI) and a Python API for maximum flexibility.

Command Line Interface: Quick and Convenient

The CLI is ideal for automating documentation generation as part of your build process.

python -m python_docstring_markdown <package_dir> <output_path>

• package_dir: The path to your Python package directory.
• output_path: The desired location for the generated Markdown file(s). Use a .md extension for a single file, or specify a directory to output one .md file per module.

Example:

python -m python_docstring_markdown ./src/my_package docs/api.md

This command will crawl the my_package directory and generate a single Markdown file named api.md in the docs directory.

Python API: For Flexible Integration

For more control and integration within your Python scripts, use the Python API.

from python_docstring_markdown import crawl

# Generate documentation for a package
docs_content = crawl("./src/my_package")

# Save to a file
with open("docs/api.md", "w") as f:
    f.write(docs_content)

This code snippet demonstrates how to programmatically generate documentation and save it to a file.

Generate Markdown documentation painlessly

python-docstring-markdown brings sanity back to Python documentation. Give it a try and see how easy it can be to create professional-looking documentation.