Fix excel-related docstring errors #24503

thoo · 2018-12-30T20:02:32Z

closes DOC: Fix docstrings of Excel related functions #23494
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
passes/runs python make.py --single pandas.related-doc

Fix errors which are reported by scripts/validate_docstrings.py:

pandas.read_excel
pandas.io.formats.style.Styler.to_excel
Series.to_excel
DataFrame.to_excel

* upstream/master: DOC: Fixing broken references in the docs (pandas-dev#24497) DOC: Splitting api.rst in several files (pandas-dev#24462) Fix misdescription in escapechar (pandas-dev#24490) Floor and ceil methods during pandas.eval which are provided by numexpr (pandas-dev#24355) BUG: Pandas any() returning false with true values present (GH pandas-dev#23070) (pandas-dev#24434) Misc separable pieces of pandas-dev#24024 (pandas-dev#24488) use capsys.readouterr() as named tuple (pandas-dev#24489) REF/TST: replace capture_stderr with pytest capsys fixture (pandas-dev#24496) TST- Fixing issue with test_parquet test unexpectedly passing (pandas-dev#24480) DOC: Doc build for a single doc made much faster, and clean up (pandas-dev#24428) BUG: Fix+test timezone-preservation in DTA.repeat (pandas-dev#24483) Implement reductions from pandas-dev#24024 (pandas-dev#24484)

jreback · 2018-12-30T20:12:29Z

pandas/io/excel.py

+       Name  Value
+0   string1      1
+1   string2      2
+2  #string3      3


this hash on purpose?

It is for the last example. pd.read_excel('tmp.xlsx', index_col=0, comment='#').

Change from #string3 to #Comment to avoid confusion.

jreback · 2018-12-30T20:13:05Z

@datapythonista @WillAyd @gfyoung if any comments.

thoo · 2018-12-30T20:45:32Z

python make.py --single pandas.read_excel stops building docs after this commit 51c508c (merge upstream)

jreback · 2018-12-30T20:51:22Z

@thoo, @datapythonista just changed this a bit, can you post what happens?

thoo · 2018-12-30T21:00:45Z

I got errors like /Users/johndoe/pandas/doc/source/index.rst:110: WARNING: toctree references excluded document 'generated/pandas.read_excel' when I run python make.py --single pandas.read_excel.
I think the extensions are not built. When I run python setup.py build_ext --inplace -j 4, I just get running build_ext and no other messages/output as usual.

I just submitted the issue here #24505. Please let me know if you need any other info.

datapythonista · 2018-12-30T21:04:38Z

@thoo I just built pandas_excel on master (in Linux):

$ ./doc/make.py html --single=pandas.read_excel
Running Sphinx v1.8.2
making output directory...
[autosummary] generating autosummary for: index.rst
[autosummary] generating autosummary for: /home/mgarcia/src/pandas/doc/source/generated/pandas.read_excel.rst
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                                                                                                               
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                                                                
generating indices... genindex py-modindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in doc/build/html.

I think we do a clean before the build, and if I'm not wrong I left the clean of the doc/source/generated/ directory, but may be you can try to remove it manually if it exists.

datapythonista · 2018-12-30T21:07:18Z

Ups, sorry, my bad. I didn't have the last changes, looks like building a single API doc is broken after splitting api.rst that has been just merged. Let me take a look...

thoo · 2018-12-30T21:07:21Z

@datapythonista Thanks. I will remove doc/source/generated/.

datapythonista · 2018-12-30T21:22:40Z

Opened #24506, which should fix the problem.

datapythonista

just one minor thing, other than that lgtm. Thanks @thoo

datapythonista · 2018-12-30T21:25:57Z

pandas/io/excel.py

+    * Defaults to ``0`` : 1st sheet as a `DataFrame`
+    * ``1`` : 2nd sheet as a `DataFrame`
+    * ``"Sheet1"`` : Load sheet with name "Sheet1"
+    * ``[0,1,"Sheet5"]`` : Load first, second and sheet named "Sheet5"


Can you add spaces after the commas? Also, unless the formatting changes, I don't think we need the spaces before the colons here (it's required for the parameters, but this is a regular list).

jreback · 2018-12-30T21:38:20Z

@thoo if you'd pull from master, you should be able to build single pages now.

thoo · 2018-12-30T22:14:41Z

@jreback @datapythonista Thanks. It is working.

codecov · 2018-12-30T23:23:46Z

Codecov Report

Merging #24503 into master will decrease coverage by 49.25%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           master   #24503       +/-   ##
===========================================
- Coverage   92.31%   43.05%   -49.26%     
===========================================
  Files         166      166               
  Lines       52391    52391               
===========================================
- Hits        48363    22557    -25806     
- Misses       4028    29834    +25806

Flag	Coverage Δ
#multiple	`?`
#single	`43.05% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/generic.py	`39.83% <ø> (-56.79%)`	⬇️
pandas/io/formats/latex.py	`0% <0%> (-100%)`	⬇️
pandas/core/categorical.py	`0% <0%> (-100%)`	⬇️
pandas/io/sas/sas_constants.py	`0% <0%> (-100%)`	⬇️
pandas/tseries/plotting.py	`0% <0%> (-100%)`	⬇️
pandas/tseries/converter.py	`0% <0%> (-100%)`	⬇️
pandas/io/formats/html.py	`0% <0%> (-98.65%)`	⬇️
pandas/core/groupby/categorical.py	`0% <0%> (-95.46%)`	⬇️
pandas/io/sas/sas7bdat.py	`0% <0%> (-91.17%)`	⬇️
pandas/io/sas/sas_xport.py	`0% <0%> (-90.15%)`	⬇️
... and 125 more

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 c4ac0d6...f11bce8. Read the comment docs.

codecov · 2018-12-30T23:23:47Z

Codecov Report

Merging #24503 into master will decrease coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #24503      +/-   ##
==========================================
- Coverage   31.89%   31.88%   -0.02%     
==========================================
  Files         166      166              
  Lines       52421    52434      +13     
==========================================
- Hits        16722    16718       -4     
- Misses      35699    35716      +17

Flag	Coverage Δ
#multiple	`30.28% <ø> (-0.01%)`	⬇️
#single	`31.88% <ø> (-0.02%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/generic.py	`31.41% <ø> (ø)`	⬆️
pandas/core/internals/blocks.py	`38.09% <0%> (-0.4%)`	⬇️
pandas/core/frame.py	`27.82% <0%> (-0.14%)`	⬇️
pandas/core/reshape/reshape.py	`7.97% <0%> (-0.09%)`	⬇️
pandas/core/reshape/pivot.py	`8.77% <0%> (ø)`	⬆️
pandas/core/computation/expressions.py	`58.82% <0%> (ø)`	⬆️
pandas/plotting/_style.py	`23.65% <0%> (ø)`	⬆️
pandas/core/groupby/generic.py	`13.71% <0%> (ø)`	⬆️
pandas/core/arrays/categorical.py	`29.81% <0%> (+0.12%)`	⬆️
pandas/core/tools/datetimes.py	`27.89% <0%> (+0.29%)`	⬆️

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 100ffff...be9651e. Read the comment docs.

* upstream/master: REF/TST: replace capture_stdout with pytest capsys fixture (pandas-dev#24501) BUG: fix .iat assignment creates a new column (pandas-dev#24495) DOC: add checks on the returns section in the docstrings (pandas-dev#23138) (pandas-dev#23432) ENH: Add strings_as_fixed_length parameter for df.to_records() (pandas-dev#18146) (pandas-dev#22229) TST: Skip db tests unless explicitly specified in -m pattern (pandas-dev#24492) Mix EA into DTA/TDA; part of 24024 (pandas-dev#24502) DOC: Fix building of a single API document (pandas-dev#24506)

thoo · 2018-12-30T23:37:59Z

It looks like pytest pandas/tests/io/test_excel.py doesn't pass on master. So hopefully that is not related to this PR.

datapythonista · 2018-12-30T23:42:24Z

there are some tests that check the content of the docstrings, so it's probably related to it, I'd take a look

jreback · 2018-12-31T23:26:35Z

thanks @thoo

thoo added 2 commits December 30, 2018 14:51

fix excel related docstring

868b7d9

jreback reviewed Dec 30, 2018

View reviewed changes

jreback added Docs IO Excel read_excel, to_excel labels Dec 30, 2018

gfyoung approved these changes Dec 30, 2018

View reviewed changes

jreback added this to the 0.24.0 milestone Dec 30, 2018

datapythonista mentioned this pull request Dec 30, 2018

DOC: Fix building of a single API document #24506

Merged

datapythonista reviewed Dec 30, 2018

View reviewed changes

fix minor syntax

f11bce8

thoo added 4 commits December 30, 2018 20:39

Retrigger :pandas-dev.pandas test fail

dfc66dd

fix failing pytests

39478a0

fix passes_na test

d16b6cd

Remove sheetname from docstring

be9651e

jreback merged commit e4cd00b into pandas-dev:master Dec 31, 2018

thoo deleted the read_excel-docstring branch January 2, 2019 20:25

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

Fix excel-related docstring errors (pandas-dev#24503)

2f1a668

Pingviinituutti pushed a commit to Pingviinituutti/pandas that referenced this pull request Feb 28, 2019

Fix excel-related docstring errors (pandas-dev#24503)

c7cae12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix excel-related docstring errors #24503

Fix excel-related docstring errors #24503

thoo commented Dec 30, 2018 •

edited by datapythonista

Loading

jreback Dec 30, 2018

thoo Dec 30, 2018

thoo Dec 30, 2018

jreback commented Dec 30, 2018

thoo commented Dec 30, 2018

jreback commented Dec 30, 2018

thoo commented Dec 30, 2018 •

edited

Loading

datapythonista commented Dec 30, 2018

datapythonista commented Dec 30, 2018

thoo commented Dec 30, 2018

datapythonista commented Dec 30, 2018

datapythonista left a comment

datapythonista Dec 30, 2018

thoo Dec 30, 2018

jreback commented Dec 30, 2018

thoo commented Dec 30, 2018

codecov bot commented Dec 30, 2018

codecov bot commented Dec 30, 2018 •

edited

Loading

thoo commented Dec 30, 2018

datapythonista commented Dec 30, 2018

jreback commented Dec 31, 2018

Fix excel-related docstring errors #24503

Fix excel-related docstring errors #24503

Conversation

thoo commented Dec 30, 2018 • edited by datapythonista Loading

jreback Dec 30, 2018

Choose a reason for hiding this comment

thoo Dec 30, 2018

Choose a reason for hiding this comment

thoo Dec 30, 2018

Choose a reason for hiding this comment

jreback commented Dec 30, 2018

thoo commented Dec 30, 2018

jreback commented Dec 30, 2018

thoo commented Dec 30, 2018 • edited Loading

datapythonista commented Dec 30, 2018

datapythonista commented Dec 30, 2018

thoo commented Dec 30, 2018

datapythonista commented Dec 30, 2018

datapythonista left a comment

Choose a reason for hiding this comment

datapythonista Dec 30, 2018

Choose a reason for hiding this comment

thoo Dec 30, 2018

Choose a reason for hiding this comment

jreback commented Dec 30, 2018

thoo commented Dec 30, 2018

codecov bot commented Dec 30, 2018

Codecov Report

codecov bot commented Dec 30, 2018 • edited Loading

Codecov Report

thoo commented Dec 30, 2018

datapythonista commented Dec 30, 2018

jreback commented Dec 31, 2018

thoo commented Dec 30, 2018 •

edited by datapythonista

Loading

thoo commented Dec 30, 2018 •

edited

Loading

codecov bot commented Dec 30, 2018 •

edited

Loading