Merge pull request #11011 from terrytangyuan/reformatDocstring

DOC: Docstring Redesign to fix the problem of unexpected keyword arg (issue10888)

Author: jreback

doc/source/whatsnew/v0.17.0.txt

@@ -1033,7 +1033,7 @@ Bug Fixes
 - Bug in vectorised setting of timestamp columns with python ``datetime.date`` and numpy ``datetime64`` (:issue:`10408`, :issue:`10412`)
 - Bug in ``Index.take`` may add unnecessary ``freq`` attribute (:issue:`10791`)
 - Bug in ``merge`` with empty ``DataFrame`` may raise ``IndexError`` (:issue:`10824`)
-
+- Bug in ``to_latex`` where unexpected keyword argument for some documented arguments (:issue:`10888`)
 
 - Bug in ``read_csv`` when using the ``nrows`` or ``chunksize`` parameters if file contains only a header line (:issue:`9535`)
 - Bug in serialization of ``category`` types in HDF5 in presence of alternate encodings. (:issue:`10366`)

pandas/core/format.py

@@ -24,11 +24,9 @@
 import itertools
 import csv
 
-docstring_to_string = """
-     Parameters
-     ----------
-     frame : DataFrame
-         object to render
+common_docstring = """
+    Parameters
+    ----------
     buf : StringIO-like, optional
         buffer to write to
     columns : sequence, optional
@@ -51,20 +49,27 @@
     sparsify : bool, optional
         Set to False for a DataFrame with a hierarchical index to print every
         multiindex key at each row, default True
+    index_names : bool, optional
+        Prints the names of the indexes, default True"""
+
+justify_docstring  = """
     justify : {'left', 'right'}, default None
         Left or right-justify the column labels. If None uses the option from
         the print configuration (controlled by set_option), 'right' out
-        of the box.
-    index_names : bool, optional
-        Prints the names of the indexes, default True
+        of the box."""
+
+force_unicode_docstring = """
     force_unicode : bool, default False
         Always return a unicode result. Deprecated in v0.10.0 as string
-        formatting is now rendered to unicode by default.
+        formatting is now rendered to unicode by default."""
+
+return_docstring = """
 
     Returns
     -------
     formatted : string (or unicode, depending on data and options)"""
 
+docstring_to_string = common_docstring + justify_docstring + force_unicode_docstring + return_docstring
 
 class CategoricalFormatter(object):
 

pandas/core/frame.py

@@ -1413,7 +1413,7 @@ def to_stata(
                              write_index=write_index)
         writer.write_file()
 
-    @Appender(fmt.docstring_to_string, indents=1)
+    @Appender(fmt.common_docstring + fmt.justify_docstring + fmt.return_docstring, indents=1)
     def to_string(self, buf=None, columns=None, col_space=None,
                   header=True, index=True, na_rep='NaN', formatters=None,
                   float_format=None, sparsify=None, index_names=True,
@@ -1441,7 +1441,7 @@ def to_string(self, buf=None, columns=None, col_space=None,
             result = formatter.buf.getvalue()
             return result
 
-    @Appender(fmt.docstring_to_string, indents=1)
+    @Appender(fmt.common_docstring + fmt.justify_docstring + fmt.return_docstring, indents=1)
     def to_html(self, buf=None, columns=None, col_space=None, colSpace=None,
                 header=True, index=True, na_rep='NaN', formatters=None,
                 float_format=None, sparsify=None, index_names=True,
@@ -1491,7 +1491,7 @@ def to_html(self, buf=None, columns=None, col_space=None, colSpace=None,
         if buf is None:
             return formatter.buf.getvalue()
 
-    @Appender(fmt.docstring_to_string, indents=1)
+    @Appender(fmt.common_docstring + fmt.return_docstring, indents=1)
     def to_latex(self, buf=None, columns=None, col_space=None, colSpace=None,
                  header=True, index=True, na_rep='NaN', formatters=None,
                  float_format=None, sparsify=None, index_names=True,