Hi all, I am in agreement with Mazi here, I prefer the numpy doc format to the standard sphinx format as it is less verbose and generally easier on the eyes in its raw state. It would also make it a bit easier to refactor docstrings from older code since the format is more similar.
Alex On Mon, Jul 29, 2013 at 10:24 PM, Boustani, Maziyar (398F) < [email protected]> wrote: > Hi all, > > While I was looking for OCW documentations and the Sphinx library I found > three different formats for documenting python codes (functions). > Default Sphinx format, numpydoc and google-doc are three formats. > Here are three of them (both actual code and html output after): > > > ++++++++++++++++++++++++++++++++ default Sphinx format > ++++++++++++++++++++++++++++++++++++ > > def default_sphinx(param1, param2, param3): > """This function does something and returns one string and one integer. > > :param param1: First parameter > :type param1: string > :param param2: Second parameter > :type param2: integer > :param param3: third parameter (optional) > :type param3: object > :returns: The outputs are string and integer in form of (out1, out2) > :rtype: (string, integer) > > """ > > test.default_sphinx(param1, param2, > param3)<file:///Users/MBoustani/Documents/python/examples/Sphinx/_build/html/code.html#test.default_sphinx> > > This function does something and returns one string and one integer. > > Parameters: > > * param1 (string) – First parameter > * param2 (integer) – Second parameter > * param3 (object) – third parameter (optional) > > > Returns: > The outputs are string and integer in form of (out1, out2) > > Return type: > (string, integer) > > > ++++++++++++++++++++++++++++++++ numpy doc format > ++++++++++++++++++++++++++++++++++++ > > def numpy_doc(param1, param2, param3): > """This function does something and returns one string and one integer > > Parameters > ---------- > param1 : string > First parameter. > param2 : integer > Second parameter. > param3 : object, optional > Third parameter. > > Returns > ------- > out1 : string > Output one. > out2 : integer > Output two. > """ > > test.numpy_doc(param1, param2, > param3)<file:///Users/MBoustani/Documents/python/examples/Sphinx/_build/html/code.html#test.numpy_doc> > > This function does something and returns one string and one integer > > Parameters : > param1 : string > First parameter. > param2 : integer > Second parameter. > param3 : object, optional > Third parameter. > > Returns : > out1 : string > Output one. > out2 : integer > Output two. > > > > ++++++++++++++++++++++++++++++++ google doc format > ++++++++++++++++++++++++++++++++++++ > def google_doc(param1, param2, param3): > """This function does something and returns one string and one integer > > Args: > param1 : string > First parameter. > param2 : integer > Second parameter. > param3 : object, optional > Third parameter. > > Returns: > out1 : string > Output one. > out2 : integer > Output two. > """ > > test.google_doc(param1, param2, > param3)<file:///Users/MBoustani/Documents/python/examples/Sphinx/_build/html/code.html#test.google_doc> > > This function does something and returns one string and one integer > > Args: > > param1 : string > First parameter. > param2 : integer > Second parameter. > param3 : object, optional > Third parameter. > Returns: > > out1 : string > Output one. > out2 : integer > Output two. > > I personally like the numpydoc format because not only the HTML format is > more clear and easy understanding but also the actual code is in better > format than default Sphinx format. > Sphinx format has ugly format in the actual code and also the HTML format > is not very clear. Specially the 'returns' values are not specified for > each return value and it gets messy if there are more that one value to > return. > > Please share what you think and leave feedback. > > Best regards, > Mazi > > -- Alex Goodman
