julianjjo / doc2md

Python docstring to markdown converter [very lightweight and specialized for personal usage]

doc2md

Simplistic utility to extract docstrings from a module or class and throw them into a simple GitHub Flavoured Markdown document. Its purpose is to quickly generate README.md files for small projects.

• Project status
• Installation
• Usage
• License
• API

Project status

I stopped using this package and therefore will not push any updates (I now usually write README.rst manually). Nonetheless, you may still find it useful. Should you encounter bugs or have improvements, feel free to submit a PR. If you want to take over maintenance, feel free to contact me.

For a more feature-rich and well maintained alternative, see:

• https://github.com/NiklasRosenstein/pydoc-markdown/ (I didn't try it)

Installation

No installation necessary. However, if you want:

$ pip install doc2md

Usage

You can run this script from the command line like:

$ doc2md.py [-a] [--no-toc] [-t title] [-d depth] module-name [class-name] \
    > README.md

At the moment this is suited only for a very specific use case. It is hardly forseeable, if I will decide to improve on it in the near future.

For a simple example output document, see the generated README (i.e. the github frontpage). It is extracted from the doc2md.py file using this very utility:

$ ./doc2md.py -a -d1 doc2md > README.md

License

Copyright © 2013-2017 Thomas Gläßle [email protected]

This work is free. You can redistribute it and/or modify it under the terms of the MIT license. See the COPYING file for more details.

This program is free software. It comes without any warranty, to the extent permitted by applicable law.

API

• doctrim
• doc2md

doctrim

Clean up indentation from docstrings.

Any whitespace that can be uniformly removed from the second line onwards is removed.

doc2md

Convert a docstring to a markdown text.