Here [1] is the wiki page I created that has both code and HTML as screenshot. I mostly like the numpydoc format. As I said it is easy to read on both code and HTML version, and also very easy to write the documentation. "numpydoc" is the extension of Sphinx and very easy to install and use (1- easy_install numpydoc 2- add 'numpydoc' in the conf.py). Sphinx will take care of style of document such as coloring, making text bold and more. I guess it is a good idea to choose the doc format before we develop more code.
[1]: https://cwiki.apache.org/confluence/display/CLIMATE/OCW+Python+documentation+different+formats Best regards, Mazi On Jul 30, 2013, at 8:38 AM, Cameron Goodale wrote: 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]<mailto:[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]<mailto:[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]<mailto:[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
