abcwalk · October 20, 2024 16:17 · Mar 23, 2017 · Mar 23, 2017 · Mar 23, 2017 · Mar 23, 2017
diff --git a/Different_style_guide_python.md b/Different_style_guide_python.md
@@ -94,6 +94,6 @@ It is possible to use a tool like Pyment to automatically generate docstrings to
 
 Note: The examples are taken from the Pyment documentation
 
-Refer:
-http://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format
+Refer:<br>
+http://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format<br>
 https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
diff --git a/Different_style_guide_python.md b/Different_style_guide_python.md
@@ -92,4 +92,8 @@ Converting/Generating
 
 It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.
 
-Note: The examples are taken from the Pyment documentation
+Note: The examples are taken from the Pyment documentation
+
+Refer:
+http://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format
+https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
diff --git a/Different_style_guide_python.md b/Different_style_guide_python.md
@@ -11,7 +11,7 @@ There follows the main used formats for docstrings.
 Historically a javadoc like style was prevalent, so it was taken as a base for Epydoc (with the called Epytext format) to generate documentation.
 
 Example:
-
+```
 """
 This is a javadoc style.
 
@@ -20,12 +20,13 @@ This is a javadoc style.
 @return: this is a description of what is returned
 @raise keyError: raises an exception
 """
+```
 ## - reST
 
 Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation. Note: it is used by default in JetBrains PyCharm (type triple quotes after defining a method and hit enter). It is also used by default as output format in Pyment.
 
 Example:
-
+```
 """
 This is a reST style.
 
@@ -34,12 +35,13 @@ This is a reST style.
 :returns: this is a description of what is returned
 :raises keyError: raises an exception
 """
+```
 ## - Google
 
 Google has their own format that is often used. It also can be interpreted by Sphinx.
 
 Example:
-
+```
 """
 This is an example of Google style.
 
@@ -53,12 +55,13 @@ Returns:
 Raises:
     KeyError: Raises an exception.
 """
+```
 Even more examples
 
 ## - Numpydoc
 
 Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.
-
+```
 """
 My numpydoc description of a kind
 of very exhautive numpydoc format docstring.
@@ -84,6 +87,7 @@ KeyError
 OtherError
     when an other error
 """
+```
 Converting/Generating
 
 It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.

diff --git a/Different_style_guide_python.md b/Different_style_guide_python.md
@@ -0,0 +1,91 @@
+## Formats
+
+Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in that tuto.
+
+Note that the reST is recommended by the PEP 287
+
+There follows the main used formats for docstrings.
+
+## - Epytext
+
+Historically a javadoc like style was prevalent, so it was taken as a base for Epydoc (with the called Epytext format) to generate documentation.
+
+Example:
+
+"""
+This is a javadoc style.
+
+@param param1: this is a first param
+@param param2: this is a second param
+@return: this is a description of what is returned
+@raise keyError: raises an exception
+"""
+## - reST
+
+Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation. Note: it is used by default in JetBrains PyCharm (type triple quotes after defining a method and hit enter). It is also used by default as output format in Pyment.
+
+Example:
+
+"""
+This is a reST style.
+
+:param param1: this is a first param
+:param param2: this is a second param
+:returns: this is a description of what is returned
+:raises keyError: raises an exception
+"""
+## - Google
+
+Google has their own format that is often used. It also can be interpreted by Sphinx.
+
+Example:
+
+"""
+This is an example of Google style.
+
+Args:
+    param1: This is the first param.
+    param2: This is a second param.
+
+Returns:
+    This is a description of what is returned.
+
+Raises:
+    KeyError: Raises an exception.
+"""
+Even more examples
+
+## - Numpydoc
+
+Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.
+
+"""
+My numpydoc description of a kind
+of very exhautive numpydoc format docstring.
+
+Parameters
+----------
+first : array_like
+    the 1st param name `first`
+second :
+    the 2nd param
+third : {'value', 'other'}, optional
+    the 3rd param, by default 'value'
+
+Returns
+-------
+string
+    a value in a string
+
+Raises
+------
+KeyError
+    when a key error
+OtherError
+    when an other error
+"""
+Converting/Generating
+
+It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.
+
+Note: The examples are taken from the Pyment documentation
No results found