MyDocstring is a small Python package that allows you to extract docstrings display them as either plain-text, Markdown, or JSON data.

• Support for Python-code (support for C-code is planned).
• Support for Google-style docstrings
• Produces JSON, plain-text, and Markdown output for modules, classes, functions, and methods.

You can begin extracting and converting docstrings using the command line tool mydocstring that comes with package. Simply type mydocstring --help to see how to use it.

Let's extract the docstring from the following example code and convert it to Markdown:

def example_function(arg1, arg2=1):
    """
    This is an example of a docstring that conforms to the Google style guide. 
    The indentation uses four spaces (no tabs). Note that each section starts
    with a header such as `Arguments` or `Returns` and its contents is indented.

    Arguments:

        arg1 (`int`): This description for this argument fits on one line.
        arg2 (`int`, optional): This description is too long to fit on a
            single line. Note that it is continued by being indented. 

    Returns:

        `bool` :  Stating the return type here is optional.

        We can continue putting explanations in this section as long as the text
        is indented.

    This text is no longer indented and therefore not part of the `Returns`
    section.

    Raises:

        ValueError: This is exception is raised when arg1 and arg2 are equal.

    """
    if arg1 == arg2:
        raise ValueError("`arg1` and `arg2` cannot be equal.")
    if arg1 > arg2:
        return True
    else: 
        return False

This example code can be found here: examples/example.py.

To convert to Markdown, we simply use

$ docstring examples/example.py example_function --markdown > examples/example_py.md

The following rendered Markdown is produced:

def example_function(arg1, arg2=1):

This is an example of a docstring that conforms to the Google style guide. The indentation uses four spaces (no tabs). Note that each section starts with a header such as Arguments or Returns and its contents is indented.

• arg1 (int) : This description for this argument fits on one line.
• arg2 (int, optional) : This description is too long to fit on a single line. Note that it is continued by being indented.

• Stating the return type here is optional.

We can continue putting explanations in this section as long as the text is indented.

This text is no longer indented and therefore not part of the Returns section.

• ValueError : This is exception is raised when arg1 and arg2 are equal.

def example_function(arg1, arg2=1):
    if arg1 == arg2:
        raise ValueError("`arg1` and `arg2` cannot be equal")
    if arg1 > arg2:
        return True
    else: 
        return False

The output above can also be found here: examples/example_py.md.

If you are not satisfied with the resulting Markdown, you can provide your own mako template

$ docstring examples/example.py example_function --markdown --template customization.md

Go to mydocstring/templates/ to see how to make your own template.

It is also possible to output plain-text, or JSON-data using the flags args --text and --json. Example output can be found here: examples/.

The package is available on the Python packaging index PyPi and can be installed via pip as follows.

$ pip install mydocstring

This project uses:

• docopt for the command-line interface application.
• mako for producing markdown templates.
• pytest for testing.

If you are having problems extracting your docstrings, or parts of their content end up missing, then please make sure that your are only using spaces (no tabs). Four spaces should be used for each level of indentation. Also, make sure that you conform to the Google style guide when writing your docstrings.

Otherwise, please submit a new issue using the issue tracker and explain the problem.

Contributions are more than welcome. Please reach out via the issue tracker to discuss and also see here for some guidelines.

If you end up using this tool in your project in one way or another. I would love to hear about it and showcase it here. Please go ahead and make a pull request.

These are some projects that inspired me to develop this tool.

• pdoc A tool for auto-generating API documentation for Python libraries.
• mkdocs Static site generator for building documentation using markdown.
• moxygen Doxygen XML to Markdown converter.
• napoleon Sphinx extension that can parse numpy and Google-style docstrings.
• pypydoxify Converts Python comments into Doxygen's syntax.
• docsify Markdown-based documentation site generator.

This project is licensed under the MIT License - see the LICENSE.md file for details.