DOC: update the pandas.DataFrame.to_string docstring #20173

Tomasz-Kluczkowski · 2018-03-10T15:14:12Z

Had to correct parameters descriptions in common docstrings (format.py) as well as in frame.py.

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
#################### Docstring (pandas.DataFrame.to_string) ####################
################################################################################

Render a DataFrame to a console-friendly tabular output.

Convert DataFrame object into a string (or unicode) representation
which can be shown in command line interface.

See Also
--------
pandas.DataFrame.to_html
    Convert dataframe to a html file.

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

Parameters
----------
buf : StringIO-like, optional
    Buffer to write to.
columns : sequence, optional, default None
    The subset of columns to write. The default None writes all columns.
col_space : int, optional
    The minimum width of each column.
header : bool, optional
    Write out the column names. If a list of strings is given, it is assumed to be aliases for the column names.
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, default None
    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.
line_width : int, optional, default no wrap
    Width to wrap a line in characters.
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's dimensions (number of rows by number of columns).

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.

Returns
-------
formatted : str (or unicode, depending on data and options)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.to_string" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

closes #xxxx
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

Had to correct parameters descriptions in common docstrings (format.py) as well as in frame.py.

…tters parameter description.

kynan · 2018-03-10T15:19:48Z

pandas/io/formats/format.py

-    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.
+        %(header)s.


Substituting the header here won't break lines at 79 characters. Not sure this is worth fixing though.

hissashirocha · 2018-03-10T15:58:27Z

pandas/core/frame.py

+        See Also
+        --------
+        pandas.DataFrame.to_html
+            Convert dataframe to a html file.


The method explanation should be after the method itself separated by space, colon (:) and space. A second line is allowed if the explanation doesn't fit in one line.

hissashirocha · 2018-03-10T16:00:44Z

pandas/io/formats/format.py

@@ -53,35 +53,38 @@
    Parameters


Parameters should go before the See Also section, right after the Extended Summary.

hissashirocha · 2018-03-10T16:02:58Z

pandas/io/formats/format.py

 """

 return_docstring = """
-
    Returns


The Returns section should go after the Parameters section and before the See Also section.

hissashirocha · 2018-03-10T16:08:45Z

pandas/io/formats/format.py

    Returns
    -------
-    formatted : string (or unicode, depending on data and options)"""
+    formatted : str (or unicode, depending on data and options)


The return explanation is missing. It should go in the next line, indented.

Tomasz-Kluczkowski · 2018-03-13T10:26:51Z

Hi,

I have a bit of a problem here as the docstring for this method is a result of concatenation of common docstrings, method’s docstring and a return docstring.
Therefore it looks like it is missing some parts or they are not in the right order but I believe the deciding factor here should be the actual html built by sphinx and it looks ok to me.
I shall add a return description though and recheck this again and post a result of html build by sphinx to confirm the final result.
Thx for reviewing.

Fixed See Also description to match the standard.

codecov · 2018-03-13T21:53:19Z

Codecov Report

Merging #20173 into master will decrease coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master   #20173      +/-   ##
==========================================
- Coverage    91.9%    91.9%   -0.01%     
==========================================
  Files         160      160              
  Lines       49892    49891       -1     
==========================================
- Hits        45852    45851       -1     
  Misses       4040     4040

Flag	Coverage Δ
#multiple	`90.28% <100%> (-0.01%)`	⬇️
#single	`42.1% <100%> (-0.01%)`	⬇️

Impacted Files	Coverage Δ
pandas/io/formats/format.py	`98.24% <100%> (-0.01%)`	⬇️
pandas/core/frame.py	`97.19% <100%> (ø)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5380fcd...bef020a. Read the comment docs.

Tomasz-Kluczkowski · 2018-03-13T22:10:01Z

As an attachement there is a zipped html rendering of the command:
python make.py html --single pandas.DataFrame.to_string
for modified docstring for pandas.DataFrame.to_string.

pandas.DataFrame.to_string.zip

It looks ok to me.
We have to remember that under the method itself there will be only See Also and Examples as the rest is pulled automatically from the common docstrings in format.py.

WillAyd · 2018-07-07T14:34:05Z

Taking a look at this one!

…string

WillAyd · 2018-07-07T15:37:18Z

Ended up being a rather complicated fixup - @datapythonista could use a second set of eyes if you have time

…string

WillAyd · 2018-07-10T00:06:44Z

Thanks @Tomasz-Kluczkowski !

Tomasz-Kluczkowski added 2 commits March 10, 2018 14:55

Fixed docstring for the DataFrame.to_string method.

7fd8464

Had to correct parameters descriptions in common docstrings (format.py) as well as in frame.py.

Shortened parameters to param. to make line <= 79 characters in forma…

f9f436a

…tters parameter description.

kynan approved these changes Mar 10, 2018

View reviewed changes

hissashirocha reviewed Mar 10, 2018

View reviewed changes

jorisvandenbossche added the Docs label Mar 12, 2018

Added returns description as per standard.

d4156f5

Fixed See Also description to match the standard.

WillAyd added 3 commits July 7, 2018 09:44

DOCstring fixup

42ea45f

Merge remote-tracking branch 'upstream/master' into add_docstring_to_…

c7dd12e

…string

Shared argument fixup

acd5d1d

WillAyd added 4 commits July 7, 2018 14:09

PY27 compat

40cb3aa

Merge remote-tracking branch 'upstream/master' into add_docstring_to_…

eb91702

…string

Merge remote-tracking branch 'upstream/master' into add_docstring_to_…

9b254eb

…string

Merge remote-tracking branch 'upstream/master' into add_docstring_to_…

bef020a

…string

WillAyd merged commit da6e26d into pandas-dev:master Jul 10, 2018

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

DOC: update the pandas.DataFrame.to_string docstring (pandas-dev#20173)

ba091c0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the pandas.DataFrame.to_string docstring #20173

DOC: update the pandas.DataFrame.to_string docstring #20173

Tomasz-Kluczkowski commented Mar 10, 2018 •

edited

Loading

kynan Mar 10, 2018

hissashirocha Mar 10, 2018

hissashirocha Mar 10, 2018

hissashirocha Mar 10, 2018

hissashirocha Mar 10, 2018

Tomasz-Kluczkowski commented Mar 13, 2018

codecov bot commented Mar 13, 2018 •

edited

Loading

Tomasz-Kluczkowski commented Mar 13, 2018

WillAyd commented Jul 7, 2018

WillAyd commented Jul 7, 2018

WillAyd commented Jul 10, 2018

DOC: update the pandas.DataFrame.to_string docstring #20173

DOC: update the pandas.DataFrame.to_string docstring #20173

Conversation

Tomasz-Kluczkowski commented Mar 10, 2018 • edited Loading

kynan Mar 10, 2018

Choose a reason for hiding this comment

hissashirocha Mar 10, 2018

Choose a reason for hiding this comment

hissashirocha Mar 10, 2018

Choose a reason for hiding this comment

hissashirocha Mar 10, 2018

Choose a reason for hiding this comment

hissashirocha Mar 10, 2018

Choose a reason for hiding this comment

Tomasz-Kluczkowski commented Mar 13, 2018

codecov bot commented Mar 13, 2018 • edited Loading

Codecov Report

Tomasz-Kluczkowski commented Mar 13, 2018

WillAyd commented Jul 7, 2018

WillAyd commented Jul 7, 2018

WillAyd commented Jul 10, 2018

Tomasz-Kluczkowski commented Mar 10, 2018 •

edited

Loading

codecov bot commented Mar 13, 2018 •

edited

Loading