> 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.
I don't want to try to quote through all your emails, so I'm just moving down the part I'm replying. Also, I can't see the picture you've linked to. Check out http://s.apache.org/9Lm for an example of the doc formatting for sphinx and google style and http://s.apache.org/Ekz for what it looks like compiled. 1) We can adjust the return value formatting. We don't have to separate them into return and return type (in fact a lot of people do this). There's also nothing stopping us from adding some whitespace to the sphinx formatting to make it easier to read in the code. I don't see how this is much harder to read than most Javadoc-esque doc strings. Sure, the type of variables is a separate line but the formatting is consistent and not complicated. 2) If documenting more than one return value is a challenge, I think the python documentation system is trying to hint at something =) 3) I'm of the opinion that we should stick with the format that generates the best looking documentation with the least amount of work. Most likely, no one is going to take the time to sit down and write up super pretty documentation like the Python docs (which auto-generate nothing/not that much). We're going to auto-generate the majority of the documentation and leave it be (which also means we don't have to update the docs in two different locations, which is also a plus). In my opinion, the Sphinx format generates the nicest output (in terms of general spacing/formatting and bolding/highlighting). The google format is a close second for me, and I think we could make it look just as nice with some extra work, but the general layout of the sphinx form looks better. 4) One plus for the non-sphinx formats is that it doesn't kill readability in the __doc__ attribute. That being said, I still think that auto-generation formatting > this. 5) I don't think this should be a huge priority. Having something that works now is great. We can always come back and change the formatting later. I think our priority right now needs to be moving the existing code base over to the new package. I think making a JIRA to collect these ideas would be convenient and still serve as a reminder. -- Joyce On Mon, Jul 29, 2013 at 10:42 PM, Goodman, Alexander (398J-Affiliate) < [email protected]> wrote: > 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 >
