DOC: update the to_excel docstring

pandas/core/generic.py

@@ -1591,62 +1591,88 @@ def _repr_latex_(self):
     # I/O Methods
 
     _shared_docs['to_excel'] = """
-    Write %(klass)s to an excel sheet
-    %(versionadded_to_excel)s
+    Write %(klass)s to an excel sheet.
+
+    To write a %(klass)s to an excel .xlsx file it is necessary to first create
+    an ExcelWriter object with a target file name, and specify a sheet in the
+    file to write to. Multiple sheets may be written to by
+    specifying unique sheet_name. With all data written to the file it is
+    necessary to save the changes. Note that creating an ExcelWriter object
+    with a file name that already exists will result in the contents of the
+    existing file being erased.
 
     Parameters
     ----------
     excel_writer : string or ExcelWriter object
-        File path or existing ExcelWriter
+        File path or existing ExcelWriter.
     sheet_name : string, default 'Sheet1'
-        Name of sheet which will contain DataFrame
+        Name of sheet which will contain DataFrame.
     na_rep : string, default ''
-        Missing data representation
+        Missing data representation.
     float_format : string, default None
-        Format string for floating point numbers
+        Format string for floating point numbers.
     columns : sequence, optional
-        Columns to write
+        Columns to write.
     header : boolean or list of string, default True
         Write out the column names. If a list of strings is given it is
-        assumed to be aliases for the column names
+        assumed to be aliases for the column names.
     index : boolean, default True
-        Write row names (index)
+        Write row names (index).
     index_label : string or sequence, default None
         Column label for index column(s) if desired. If None is given, and
         `header` and `index` are True, then the index names are used. A
         sequence should be given if the DataFrame uses MultiIndex.
-    startrow :
-        upper left cell row to dump data frame
-    startcol :
-        upper left cell column to dump data frame
+    startrow : integer, default 0
+        Upper left cell row to dump data frame.
+    startcol : integer, default 0
+        Upper left cell column to dump data frame.
     engine : string, default None
-        write engine to use - you can also set this via the options
+        Write engine to use - you can also set this via the options
         ``io.excel.xlsx.writer``, ``io.excel.xls.writer``, and
         ``io.excel.xlsm.writer``.
     merge_cells : boolean, default True
         Write MultiIndex and Hierarchical Rows as merged cells.
-    encoding: string, default None
-        encoding of the resulting excel file. Only necessary for xlwt,
+    encoding : string, default 'ascii'
+        Encoding of the resulting excel file. Only necessary for xlwt,
         other writers support unicode natively.
     inf_rep : string, default 'inf'
         Representation for infinity (there is no native representation for
-        infinity in Excel)
+        infinity in Excel).
+    verbose : boolean, default True
+        Display more information in the error logs.
     freeze_panes : tuple of integer (length 2), default None
         Specifies the one-based bottommost row and rightmost column that
-        is to be frozen
+        is to be frozen.
 
-        .. versionadded:: 0.20.0
+        .. versionadded:: 0.20.0.
+
+    Returns
+    -------
+    Nothing returned.
+
+    See Also
+    --------
+    pd.read_excel
+
+    Examples
+    --------
+
+    >>> df1 = pd.DataFrame([['a', 'b'], ['c', 'd']],
+    ...                   index=['row 1', 'row 2'],
+    ...                   columns=['col 1', 'col 2'])
+    >>> writer = pd.ExcelWriter('output.xlsx', engine='xlsxwriter')
+    >>> df1.to_excel(writer, sheet_name='Sheet1')
+    >>> writer.save()
 
-    Notes
-    -----
     If passing an existing ExcelWriter object, then the sheet will be added
     to the existing workbook.  This can be used to save different
     DataFrames to one workbook:
 
-    >>> writer = pd.ExcelWriter('output.xlsx')
-    >>> df1.to_excel(writer,'Sheet1')
-    >>> df2.to_excel(writer,'Sheet2')
-    >>> writer.save()
+    >>> writer2 = pd.ExcelWriter('output2.xlsx', engine='xlsxwriter')
+    >>> df1.to_excel(writer2, sheet_name='Sheet1')
+    >>> df2 = df1.copy()
+    >>> df2.to_excel(writer2, sheet_name='Sheet2')
+    >>> writer2.save()
 
     For compatibility with to_csv, to_excel serializes lists and dicts to
     strings before writing.