Working on the pandas doc guide

Author: datapythonista

docs/pandas-doc/build/.doctrees/contents.doctree

@@ -72,3 +72,237 @@ about reStructuredText can be found in:
 
 The rest of this document will summarize all the above guides, and will
 provide additional convention specific to the pandas project.
+
+Writing a docstring
+-------------------
+
+General rules
+~~~~~~~~~~~~~
+
+Docstrings must be defined with three double-quotes. No blank lines should be
+left before or after the docstring. The text starts immediately after the
+opening quotes (not in the next line). The closing quotes have their own line
+(and are not added at the end of the last sentence).
+
+**Good:**
+
+.. code-block:: python
+
+    def func():
+        """Some function.
+
+        With a good docstring.
+        """
+        foo = 1
+        bar = 2
+        return foo + bar
+
+**Bad:**
+
+.. code-block:: python
+
+    def func():
+
+        """
+        Some function.
+
+        With several mistakes in the docstring.
+        
+        It has a blank like after the signature `def func():`.
+        
+        The text 'Some function' should go in the same line as the
+        opening quotes of the docstring, not in the next line.
+        
+        There is a blank line between the docstring and the first line
+        of code `foo = 1`.
+        
+        The closing quotes should be in the next line, not in this one."""
+
+        foo = 1
+        bar = 2
+        return foo + bar
+
+Section 1: Short summary
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The short summary is a single sentence that express what the function does in a
+concise way.
+
+The short summary must start with a verb infinitive, end with a dot, and fit in
+a single line. It needs to express what the function does without providing
+details.
+
+**Good:**
+
+.. code-block:: python
+
+    def astype(dtype):
+        """Cast Series type.
+
+        This section will provide further details.
+        """
+        pass
+
+**Bad:**
+
+.. code-block:: python
+
+    def astype(dtype):
+        """Casts Series type.
+
+        Verb in third-person of the present simple, should be infinitive.
+        """
+        pass
+
+    def astype(dtype):
+        """Method to cast Series type.
+
+        Does not start with verb.
+        """
+        pass
+
+    def astype(dtype):
+        """Cast Series type
+
+        Missing dot at the end.
+        """
+        pass
+
+    def astype(dtype):
+        """Cast Series type from its current type to the new type defined in
+        the parameter dtype.
+
+        Summary is too verbose and doesn't fit in a single line.
+        """
+        pass
+
+Section 2: Extended summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The extended summary provides details on what the function does. It should not
+go into the details of the parameters, or discuss implementation notes, which
+go in other sections.
+
+A blank line is left between the short summary and the extended summary. And
+every paragraph in the extended summary is finished by a dot.
+
+.. code-block:: python
+
+    def unstack():
+        """Pivot a row index to columns.
+
+        When using a multi-index, a level can be pivoted so each value in
+        the index becomes a column. This is especially useful when a subindex
+        is repeated for the main index, and data is easier to visualize as a
+        pivot table.
+
+        The index level will be automatically when added as columns.
+        """
+        pass
+
+Section 3: Parameters
+~~~~~~~~~~~~~~~~~~~~~
+
+The details of the parameters will be added in this section. This section has
+the title "Parameters", followed by a line with a hyphen under each letter of
+the word "Parameters". A blank line is left before the section title, but not
+after, and not between the line with the word "Parameters" and the one with
+the hyphens.
+
+After the title, each parameter in the signature must be documented, including
+`*args` and `**kwargs`, but not `self`.
+
+The parameters are defined by their name, followed by a space, a colon, another
+space, and the type (or type). Note that the space between the name and the
+colon is important. Types are not defined for `*args` and `**kwargs`, but must
+be defined for all other parameters. After the parameter definition, it is 
+required to have a line with the parameter description, which is indented, and
+can have multiple lines. The description must start with a capital letter, and
+finish with a dot.
+
+**Good:**
+
+.. code-block:: python
+
+    class Series:
+        def plot(kind, **kwargs):
+            """Generate a plot.
+
+            Render the data in the Series as a matplotlib plot of the
+            specified kind.
+
+            Parameters
+            ----------
+            kind : str
+                Kind of matplotlib plot.
+            **kwargs
+                These parameters will be passed to the matplotlib plotting
+                function.
+            """
+
+**Bad:**
+
+.. code-block:: python
+
+    class Series:
+        def plot(kind, **kwargs):
+            """Generate a plot.
+
+            Render the data in the Series as a matplotlib plot of the
+            specified kind.
+
+            Note the blank line between the parameters title and the first
+            parameter. Also, not that after the name of the parameter `kind`
+            and before the colo, a space is missing.
+
+            Also, note that the parameter descriptions do not start with a
+            capital letter, and do not finish with a dot.
+
+            Finally, the `**kwargs` is missing.
+
+            Parameters
+            ----------
+
+            kind: str
+                kind of matplotlib plot
+            """
+
+Parameter types
+^^^^^^^^^^^^^^^
+
+When specifying the parameter types, Python built-in data types can be used
+directly:
+
+- int
+- float
+- str
+
+For complex types, define the subtypes:
+
+- list of int
+- dict of str : int
+- tuple of (str, int, int)
+- set of str
+
+If the type is defined in a Python module, the module must be specified:
+
+- datetime.date
+- datetime.datetime
+- decimal.Decimal
+
+If the type is in a package, the module must be equally specified:
+
+- numpy.ndarray
+- scipy.sparse.coo_matrix
+
+If the type is a pandas type, also specify pandas:
+
+- pandas.Series
+- pandas.DataFrame
+
+If more than one type is accepted, separate them by commas, except the
+last two types, that need to be separated by the word 'or':
+
+- int or float
+- float, decimal.Decimal or None
+- str or list of str