Making API from Python docstrings written in PEP8 -

i've written code in python. tried follow common guidelines writing helpful comments @ beginnings of functions. style pep8, e.g.

def __init__(self, f_name=none, list_=none, cut_list=none, n_events=none, description=none):         """         parse lhco or root file list of event objects.          possible initialize events class without lhco file,         , later append events list.          arguments:         f_name -- name of lhco or root file, including path         list_ -- list initalizing events         cut_list -- cuts applied events , acceptance         n_events -- number of events read lhco file         description -- information events         """ 

i want automatically generate helpful api code. i've found few options , looking @ sphinx in particular. seemed wanted (though struggled make generate api, rather manual program). drawback, however, has it's own expected style docstrings:

""" :param x: parameter :type x: type """ 

is best me rewrite docstrings syntax? produce nice api, don't them in code, , it'll time consuming if turns out bad idea. standard, best practice? should convert? if so, can automatically me?

the sphinx default format docstrings quite powerful , worth time if want generate clean api documentation , if need review own code in months, years. yes, idea.

if don't default sphinx-rest syntax, try writing docstrings the way numpy do, e.g.:

def func(arg1, arg2):     """summary line.      extended description of function.      parameters     ----------     arg1 : int         description of arg1     arg2 : str         description of arg2      returns     -------     bool         description of return value      """     return true 

there's sphinx extension (napoleon) allows sphinx parse style (or google style, simpler).