DOC: update the pandas.DataFrame.to_string docstring

pandas/core/frame.py

@@ -1966,14 +1966,35 @@ def to_parquet(self, fname, engine='auto', compression='snappy',
     @Substitution(header='Write out the column names. If a list of strings '
                          'is given, it is assumed to be aliases for the '
                          'column names')
-    @Appender(fmt.docstring_to_string, indents=1)
+    @Substitution(shared_params=fmt.common_docstring,
+                  returns=fmt.return_docstring)
     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, justify=None,
                   line_width=None, max_rows=None, max_cols=None,
                   show_dimensions=False):
         """
         Render a DataFrame to a console-friendly tabular output.
+
+        %(shared_params)s
+        line_width : int, optional
+            Width to wrap a line in characters.
+
+        %(returns)s
+
+        See Also
+        --------
+        to_html : Convert DataFrame to HTML.
+
+        Examples
+        --------
+        >>> d = {'col1' : [1, 2, 3], 'col2' : [4, 5, 6]}
+        >>> df = pd.DataFrame(d)
+        >>> print(df.to_string())
+           col1  col2
+        0     1     4
+        1     2     5
+        2     3     6
         """
 
         formatter = fmt.DataFrameFormatter(self, buf=buf, columns=columns,
@@ -1994,7 +2015,8 @@ def to_string(self, buf=None, columns=None, col_space=None, header=True,
             return result
 
     @Substitution(header='whether to print column labels, default True')
-    @Appender(fmt.docstring_to_string, indents=1)
+    @Substitution(shared_params=fmt.common_docstring,
+                  returns=fmt.return_docstring)
     def to_html(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, justify=None, bold_rows=True,
@@ -2004,20 +2026,15 @@ def to_html(self, buf=None, columns=None, col_space=None, header=True,
         """
         Render a DataFrame as an HTML table.
 
-        `to_html`-specific options:
-
+        %(shared_params)s
         bold_rows : boolean, default True
             Make the row labels bold in the output
         classes : str or list or tuple, default None
             CSS class(es) to apply to the resulting html table
         escape : boolean, default True
             Convert the characters <, >, and & to HTML-safe sequences.
-        max_rows : int, optional
-            Maximum number of rows to show before truncating. If None, show
-            all.
-        max_cols : int, optional
-            Maximum number of columns to show before truncating. If None, show
-            all.
+        notebook : {True, False}, default False
+            Whether the generated HTML is for IPython Notebook.
         decimal : string, default '.'
             Character recognized as decimal separator, e.g. ',' in Europe
 
@@ -2034,6 +2051,11 @@ def to_html(self, buf=None, columns=None, col_space=None, header=True,
 
             .. versionadded:: 0.23.0
 
+        %(returns)s
+
+        See Also
+        --------
+        to_string : Convert DataFrame to a string.
         """
 
         if (justify is not None and

pandas/io/formats/format.py

@@ -45,69 +45,69 @@
 from functools import partial
 
 common_docstring = """
-    Parameters
-    ----------
-    buf : StringIO-like, optional
-        buffer to write to
-    columns : sequence, optional
-        the subset of columns to write; default None writes all columns
-    col_space : int, optional
-        the minimum width of each column
-    header : bool, optional
-        %(header)s
-    index : bool, optional
-        whether to print index (row) labels, default True
-    na_rep : string, optional
-        string representation of NAN to use, default 'NaN'
-    formatters : list or dict of one-parameter functions, optional
-        formatter functions to apply to columns' elements by position or name,
-        default None. The result of each function must be a unicode string.
-        List must be of length equal to the number of columns.
-    float_format : one-parameter function, optional
-        formatter function to apply to columns' elements if they are floats,
-        default None. The result of this function must be a unicode string.
-    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
-    line_width : int, optional
-        Width to wrap a line in characters, default no wrap
-    table_id : str, optional
-        id for the <table> element create by to_html
-
-        .. versionadded:: 0.23.0"""
+        Parameters
+        ----------
+        buf : StringIO-like, optional
+            Buffer to write to.
+        columns : sequence, optional, default None
+            The subset of columns to write. Writes all columns by default.
+        col_space : int, optional
+            The minimum width of each column.
+        header : bool, optional
+            %(header)s.
+        index : bool, optional, default True
+            Whether to print index (row) labels.
+        na_rep : str, optional, default 'NaN'
+            String representation of NAN to use.
+        formatters : list or dict of one-param. functions, optional
+            Formatter functions to apply to columns' elements by position or
+            name.
+            The result of each function must be a unicode string.
+            List must be of length equal to the number of columns.
+        float_format : one-parameter function, optional, default None
+            Formatter function to apply to columns' elements if they are
+            floats. The result of this function must be a unicode string.
+        sparsify : bool, optional, default True
+            Set to False for a DataFrame with a hierarchical index to print
+            every multiindex key at each row.
+        index_names : bool, optional, default True
+            Prints the names of the indexes.
+        justify : str, default None
+            How to justify the column labels. If None uses the option from
+            the print configuration (controlled by set_option), 'right' out
+            of the box. Valid values are
+
+            * left
+            * right
+            * center
+            * justify
+            * justify-all
+            * start
+            * end
+            * inherit
+            * match-parent
+            * initial
+            * unset.
+        max_rows : int, optional
+            Maximum number of rows to display in the console.
+        max_cols : int, optional
+            Maximum number of columns to display in the console.
+        show_dimensions : bool, default False
+            Display DataFrame dimensions (number of rows by number of columns).
+    """
 
 _VALID_JUSTIFY_PARAMETERS = ("left", "right", "center", "justify",
                              "justify-all", "start", "end", "inherit",
                              "match-parent", "initial", "unset")
 
-justify_docstring = """
-    justify : str, default None
-        How to justify the column labels. If None uses the option from
-        the print configuration (controlled by set_option), 'right' out
-        of the box. Valid values are
-
-        * left
-        * right
-        * center
-        * justify
-        * justify-all
-        * start
-        * end
-        * inherit
-        * match-parent
-        * initial
-        * unset
-"""
-
 return_docstring = """
+        Returns
+        -------
+        str (or unicode, depending on data and options)
+            String representation of the dataframe.
+    """
 
-    Returns
-    -------
-    formatted : string (or unicode, depending on data and options)"""
-
-docstring_to_string = common_docstring + justify_docstring + return_docstring
+docstring_to_string = common_docstring + return_docstring
 
 
 class CategoricalFormatter(object):
@@ -381,7 +381,7 @@ class DataFrameFormatter(TableFormatter):
     """
 
     __doc__ = __doc__ if __doc__ else ''
-    __doc__ += common_docstring + justify_docstring + return_docstring
+    __doc__ += common_docstring + return_docstring
 
     def __init__(self, frame, buf=None, columns=None, col_space=None,
                  header=True, index=True, na_rep='NaN', formatters=None,