Sorry guys for spam. Because I copy paste from local I can see them but not you, so here is the screenshot how the HTML look likes.
[cid:[email protected]] Best regards, Mazi On Jul 29, 2013, at 10:39 PM, Boustani, Maziyar (398F) wrote: The HTML formats have not appeared correctly. Here is how they look like in HTML format. 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) 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. 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. Best regards, Mazi On Jul 29, 2013, at 10:24 PM, Boustani, Maziyar (398F) 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
