DOC: Fixing even more warnings (not many left)

[datapythonista]

• xref DOC: Fix all flake8 issues and warning in the documentation pages #24173
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

Let's wait for the logs, tested locally only part of them, but this should fix most of the remaining warnings.

CC: @jorisvandenbossche

[codecov]

Codecov Report

Merging #26850 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #26850      +/-   ##
==========================================
- Coverage   91.86%   91.85%   -0.01%     
==========================================
  Files         179      179              
  Lines       50700    50700              
==========================================
- Hits        46576    46572       -4     
- Misses       4124     4128       +4

Flag	Coverage Δ
#multiple	90.45% <ø> (ø)	⬆️
#single	41.09% <ø> (-0.09%)	⬇️

Impacted Files	Coverage Δ
pandas/core/indexes/base.py	96.71% <ø> (ø)	⬆️
pandas/io/gbq.py	88.88% <0%> (-11.12%)	⬇️
pandas/core/frame.py	96.88% <0%> (-0.12%)	⬇️

---

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 8374a1d...c396d44. Read the comment docs.

[codecov]

Codecov Report

Merging #26850 into master will decrease coverage by 50.78%.
The diff coverage is 50%.

@@             Coverage Diff             @@
##           master   #26850       +/-   ##
===========================================
- Coverage   91.86%   41.08%   -50.79%     
===========================================
  Files         179      179               
  Lines       50700    50717       +17     
===========================================
- Hits        46576    20835    -25741     
- Misses       4124    29882    +25758

Flag	Coverage Δ
#multiple	?
#single	41.08% <50%> (-0.11%)	⬇️

Impacted Files	Coverage Δ
pandas/core/indexes/base.py	55.68% <50%> (-41.04%)	⬇️
pandas/io/formats/latex.py	0% <0%> (-100%)	⬇️
pandas/plotting/_matplotlib/__init__.py	0% <0%> (-100%)	⬇️
pandas/io/gcs.py	0% <0%> (-100%)	⬇️
pandas/io/sas/sas_constants.py	0% <0%> (-100%)	⬇️
pandas/core/groupby/categorical.py	0% <0%> (-100%)	⬇️
pandas/tseries/plotting.py	0% <0%> (-100%)	⬇️
pandas/io/s3.py	0% <0%> (-100%)	⬇️
pandas/io/formats/html.py	0% <0%> (-99.37%)	⬇️
pandas/io/sas/sas7bdat.py	0% <0%> (-91.16%)	⬇️
... and 133 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 8374a1d...9d104dd. Read the comment docs.

[jorisvandenbossche]

Almost! ;)

There are two left (from the ones we could solve):

/home/travis/build/pandas-dev/pandas/doc/source/reference/api/pandas.Index.asi8.rst: WARNING: document isn't included in any toctree
/home/travis/build/pandas-dev/pandas/doc/source/reference/api/pandas.api.extensions.ExtensionDtype.na_value.rst: WARNING: document isn't included in any toctree

About the ExtensionDtype.na_value: It doesn't seem generated in the actual class docstring page (http://dev.pandas.io/reference/api/pandas.api.extensions.ExtensionDtype.html#pandas.api.extensions.ExtensionDtype), so I think we can remove the comment at the bottom of https://raw.githubusercontent.com/pandas-dev/pandas/master/doc/source/reference/index.rst to avoid the warning

[datapythonista]

Didn't see where Index.asi8 is implemented, just saw the methods for subclasses of it. Let the trickier ones for the end, I'm having a look at the contributor errors, I'll open a PR to add the error returned by git to the warning.

Feel free to look at those if you want, and also:

/home/travis/miniconda3/envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:925: UserWarning: Attempting to work in a virtualenv. If you encounter problems, please install IPython inside the virtualenv.

I think we should be able to start failing on warnings today, before more are introduced. :)

[jorisvandenbossche]

I made the change locally, will push here

[datapythonista]

I just saw that the virtualenv error doesn't happen in azure, there are just 3 warnings left there according to sphinx. Better don't bother then, it's in azure where we need to add the validation.

[jorisvandenbossche]

Do you already know how you would do the validation? Can we capture and parse the log build in azure?

[datapythonista]

sphinx has parameters for that:

  -W                turn warnings into errors
  --keep-going      With -W, Keep going when getting warnings

[jorisvandenbossche]

I think we had some discussion about that before, but some problems with that: a) it doesn't handle the ipython directive errors (I think?) and b) it doesn't allow us to have some exceptions (eg to ignore our contributor directive that needs the full git history)

[jorisvandenbossche]

Refeshing my memory: we had a discussion about this in #22743. You added a --warnings-are-errors to our doc build script to basically have this -W --keep-going (#24523).
Ah, and #24661 is the proper issue to further discuss this.

[jorisvandenbossche]

Hmm, my commit didn't work, reverting.
I actually read the warning wrong: it says those two attributes are not included in any toctree, while they actually are (that's what I first tried to remove). Not sure then ..

[jorisvandenbossche]

Let's already merge those.