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
