Skip to content
Convert NumPy-styled Python docstring to Markdown.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


This piece of code can be used to convert NumPy-styled Python docstrings (example), such as those used in scikit-learn, to Markdown with minimum dependencies. In this way, only the code-contained documentation needs to be editted, and your documentation on for example readthedocs can be automatically updated thereafter with some configuration.


The converted documentation for this particular code can be found here.

Before Use

The format assumes that your code (or at least your docstring documentation) is in line with the styleguides of both PEP8 and PEP257. There are two ways to go about making sure this is the case:


Just check the example here to get a quick overview of how the docstrings would have to look in order for them to parse correctly.


The styleguides are incorporated into two libraries that can be used to check the Python files for style errors in terminal, like so:

pip install pep8
pip install pep257


These are more conveniently implemented in linter plugins such as linter-pep8 and linter-pep257 for the linter package in Atom, and Flake8Lint for Sublime Text (and pretty much every other IDE).


First clone from GitHub:

git clone

To use the script within terminal, simply type:

python3 /dir/to/ /dir/to/

If you want to automatically generate a bunch of documentation and are not comfortable with writing .sh scripts, you can use the code in Python as well:

from markdoc import MarkDoc
md = MarkDoc('/dir/to/', '/dir/to/')

You can access the converted markdown string in:

# print markdown from class attribute

The class runs itself on initialization (calls If you do not want this, you can add cold=True to the class initialization, like so:

md = MarkDoc('', '', cold=True)

Planned Fixes

  • Handle consecutive classes within the same file.
  • Fix inherrited classes being handled correctly (no __init__, no object).
  • Link class methods from table to their documentation.
  • Might not handle decorators neatly.

Docstring Issues

Some caveats:

  • Do not use """ for anything other than docstrings.
  • First line of any docstring has to contain the first short title (example).
  • Classes have to be structured new-style: class SomeClass(object):.
  • Codeblocks in examples have to be vanilla Python (>>> and ...).
  • Please do not use class as a parameter name!


Script has only been tested with Python 3.4 on Ubuntu.

You can’t perform that action at this time.