Repository: pandas-dev/pandas

Issue:
DOC: Fix the docstring of to_stata in pandas/core/frame.py
pandas docstring are expected to follow the format defined in https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html

This includes among other things:
- There is a short description fitting in one line (there can be a longer one after that).
- The description of the parameters, the returns section, and the see also items, starts with a capital letter and ends with a period.
- In the Return section there is no name before the type (e.g. `transformed : Series`) but just the type (e.g. `Series`) in the first line.
- The examples are valid PEP-8 code, and when executed, they produce the shown input.

We should make the required adjustments in the docstring of the function `to_stata` in `pandas/core/frame.py`.

We should validate the docstring with our validator (which does not validate all the formats, but some):
- `./scripts/validate_docstrings.py pandas.DataFrame.to_stata`

And we should validate the PEP-8 of the examples (note that the next command will validate the PEP-8 of all examples, just make sure that none of the shown is in the function being addressed, the rest will be fixed in separate issues):
- `flake8 --doctests pandas/core/frame.py`


Discussion:
Working on this issue, referenced from #22899 . 
@leeyspaul are you working on this? I don't think anyone else is finally working on it.
@datapythonista is this issue still open ? I would like to work on it if it is - otherwise, any other ones still open (most DOC issues seem taken) ?
Yes, this is open and I don't think there is a PR for it, or anyone working on it. So, please go ahead.
@datapythonista Thanks. Just to clarify, I don't see a Return sections currently included in the to_stata docstring - did you want that added in presumably rather than modified ?
Yes, I was just mentioning examples, but the idea is that the docstring is as good as possible and follow all the standards named in the documentation.
Thanks, will do !
@datapythonista Just submitted a PR, let me know if there are any modifications required.

Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -1856,13 +1856,16 @@ def to_stata(self, fname, convert_dates=None, write_index=True,
                  data_label=None, variable_labels=None, version=114,
                  convert_strl=None):
         """
-        Export Stata binary dta files.
+        Export DataFrame object to Stata dta format.
+
+        Writes the DataFrame to a Stata dataset file.
+        "dta" files contain a Stata dataset.
 
         Parameters
         ----------
-        fname : path (string), buffer or path object
-            string, path object (pathlib.Path or py._path.local.LocalPath) or
-            object implementing a binary write() functions. If using a buffer
+        fname : str, buffer or path object
+            String, path object (pathlib.Path or py._path.local.LocalPath) or
+            object implementing a binary write() function. If using a buffer
             then the buffer will not be automatically closed after the file
             data has been written.
         convert_dates : dict
@@ -1881,7 +1884,7 @@ def to_stata(self, fname, convert_dates=None, write_index=True,
         time_stamp : datetime
             A datetime to use as file creation date.  Default is the current
             time.
-        data_label : str
+        data_label : str, optional
             A label for the data set.  Must be 80 characters or smaller.
         variable_labels : dict
             Dictionary containing columns as keys and variable labels as
@@ -1889,7 +1892,7 @@ def to_stata(self, fname, convert_dates=None, write_index=True,
 
             .. versionadded:: 0.19.0
 
-        version : {114, 117}
+        version : {114, 117}, default 114
             Version to use in the output dta file.  Version 114 can be used
             read by Stata 10 and later.  Version 117 can be read by Stata 13
             or later. Version 114 limits string variables to 244 characters or
@@ -1921,28 +1924,16 @@ def to_stata(self, fname, convert_dates=None, write_index=True,
 
         See Also
         --------
-        pandas.read_stata : Import Stata data files.
-        pandas.io.stata.StataWriter : Low-level writer for Stata data files.
-        pandas.io.stata.StataWriter117 : Low-level writer for version 117
-            files.
+        read_stata : Import Stata data files.
+        io.stata.StataWriter : Low-level writer for Stata data files.
+        io.stata.StataWriter117 : Low-level writer for version 117 files.
 
         Examples
         --------
-        >>> data.to_stata('./data_file.dta')
-
-        Or with dates
-
-        >>> data.to_stata('./date_data_file.dta', {2 : 'tw'})
-
-        Alternatively you can create an instance of the StataWriter class
-
-        >>> writer = StataWriter('./data_file.dta', data)
-        >>> writer.write_file()
-
-        With dates:
-
-        >>> writer = StataWriter('./date_data_file.dta', data, {2 : 'tw'})
-        >>> writer.write_file()
+        >>> df = pd.DataFrame({'animal': ['falcon', 'parrot', 'falcon',
+        ...                               'parrot'],
+        ...                    'speed': [350, 18, 361, 15]})
+        >>> df.to_stata('animals.dta')  # doctest: +SKIP
         """
         kwargs = {}
         if version not in (114, 117):


Test patch: