argdoc example

argdoc.py

#!/usr/bin/env python
import inspect
import re

#: Regex that finds exception raising
RAISE_RX = re.compile('raise ([^\(]*)\(')


def test(a, b='ok', c=False):
    if False:
        raise Exception('blah')
    return ''


def generate_arg_doc(func):
    """
    Generates python argument docs.

    :param func: The function to document.
    :type func: callable
    :returns: The arg docs.
    :rtype: basestring
    """
    doc = ''

    spec = inspect.getargspec(func)
    for arg in spec.args:
        doc += ':param {}:\n:type {}:\n'.format(arg, arg)

    source = inspect.getsource(func)
    for exception in RAISE_RX.findall(source):
        doc += ':raises {}:\n'.format(exception)
    if 'return' in inspect.getsource(func):
        doc += ':returns:\n:rtype:\n'
    return doc[:-1]

if __name__ == '__main__':
    print(generate_arg_doc(test))