I believe a JIRA issue would be ideal here, since we can upload screenshots to it and discuss.
I don't have a well formed opinion at this time because i am just trying to get the code refactored and updated in ocw and out of the rcmes folder. Toward that goal I am going to keep using the format that Mike suggested and is used in dataset.py until another format is chosen and consensus is reached. Thanks, C On Tue, Jul 30, 2013 at 8:09 AM, Michael Joyce <[email protected]> wrote: > > 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 > > >
