What do we want out of our API docs? What are the current issues?

I think we're (mostly) happy with api.rst: we manually list the classes and methods that we want to include the docs, grouped by topics of our choosing.

I think we're unhappy with some aspects of the auto-genrated class pages.

The hack in our vendored numpydoc.py "fixing" the autosummary to not include a table of methods for certain classes. This avoids a ton of redundant pages with the parent class, but we can't call out important differences like RangeIndex.start

We'd like a way to limit autosummary to specific methods in a class (I think this can be done with a Methods section in the docstring)

Tasks:

  • [x] Limit API doc of classes to certain members (either extend autodoc or do it manually?) -> #18202
  • [x] DOC: fix API docs generation with sphinx 1.6 #16705
  • [x] DOC: documenting cython class (eg Timestamp): "cyfunction is not a python function" #5218 -> #18202
  • [x] Remove vendored IPython sphinxext (#18193, #19657)
  • [x] should be OK with https://github.com/ipython/ipython/pull/10907 released)
  • [x] removed in #19657
  • [ ] We should check on Windows!
  • [x] Align our numpydoc version with upstream / use upstream version: for this we somehow need to fix (or push upstream) our hacks to numpydoc ( I think this are the only relevant changes to the numpydoc source since it was last aligned with upstream in #6003) (xref #11257)):
  • [x] cf40991 initial commit for allowing classes without members table -> #18202
  • [x] 70c9d31 for None attributes
  • [x] Remove vendored numpydoc (work around https://github.com/numpy/numpydoc/pull/106#issuecomment-343220139)
  • [x] Fix cache_readonly copying docstring (https://github.com/pandas-dev/pandas/issues/18197)
  • [ ] Index.name and other class attributes. Either fix in numpydoc to use sphinx magic, or make into properties
  • [x] DataFrame.index and DataFrame.columns (#18196)
  • [x] Check performance (better than 1.6, but still slower? https://github.com/sphinx-doc/sphinx/issues/4230)

Comment From: jorisvandenbossche

I indeed think we at least want to have a way to only document certain methods/attributes on a class, to prevent including all.

Something like outlined above (with the :members: to the autosummary directive) is nice. But if we don't directly find a solution, it might be easier to go this way: for those 'problematic' classes, include the actual docstring page (which is now autogenerated, but for some classes it would not be that much work to make them ourselves) and then you can explicitly include those members me want.

Comment From: jorisvandenbossche

I think the above is somewhat the minimal we need to be able to document all classes, without an explosion of docstring pages. But, there are also other features which could be nice. Eg more automate this, and if docstrings are identical, only build it once for the base Index class, and have it for other classes link to that single docstring page

We could also try to limit the pages we currently already have (eg remove the duplicate pages for DatetimeIndex and TimedeltaIndex), but then we might need to provide redirects.

Comment From: jorisvandenbossche

So some other related issue to the API docs:

  • DOC: fix API docs generation with sphinx 1.6 https://github.com/pandas-dev/pandas/issues/16705
  • DOC: documenting cython class (eg Timestamp): "cyfunction is not a python function" #5218
  • Align our numpydoc version with upstream / use upstream version: for this we somehow need to fix (or push upstream) our hacks to numpydoc (https://github.com/pandas-dev/pandas/commit/cf40991093e746e5dde40fca4f322ecfc3dfff78 initial commit for allowing classes without members table and https://github.com/pandas-dev/pandas/commit/70c9d318ed4ef32e1c294a4dbefcb783cda19dba for None attributes -> I think this are the only relevant changes to the numpydoc source since it was last aligned with upstream in https://github.com/pandas-dev/pandas/pull/6003) (xref https://github.com/pandas-dev/pandas/pull/11257)

Comment From: TomAugspurger

For moving to IPython.sphinxext, I think the only new warnings are

source/whatsnew/v0.7.3.txt:None: WARNING: image file not readable: _static/scatter_matrix_kde.png
source/whatsnew/v0.7.3.txt:None: WARNING: image file not readable: _static/bar_plot_stacked_ex.png
source/whatsnew/v0.7.3.txt:None: WARNING: image file not readable: _static/barh_plot_stacked_ex.png

which is good because those figures don't exist. They're in source/savefig. Oh, I see that's a change from prior versions, so it used to be correct. It should be controllable with ipython_savefig_dir. https://ipython.org/ipython-doc/3/api/generated/IPython.sphinxext.ipython_directive.html#module-IPython.sphinxext.ipython_directive

Comment From: jorisvandenbossche

If we want to go completely warning free, we also have those ones in the beginning of the build:

WARNING: [autosummary] failed to import 'pandas.DataFrame.columns': no module named pandas.DataFrame.columns
WARNING: [autosummary] failed to import 'pandas.DataFrame.index': no module named pandas.DataFrame.index
WARNING: [autosummary] failed to import 'pandas.Panel.items': no module named pandas.Panel.items
WARNING: [autosummary] failed to import 'pandas.Panel.major_axis': no module named pandas.Panel.major_axis
WARNING: [autosummary] failed to import 'pandas.Panel.minor_axis': no module named pandas.Panel.minor_axis
WARNING: [autosummary] failed to import 'pandas.Series.index': no module named pandas.Series.index

Comment From: TomAugspurger

@jorisvandenbossche not sure if this will work for the cyfuncs, but see the second example here

Perhaps if we put the function signature on the first line of the docstring, numpydoc / sphinx will not attempt to introspect the cyfunc?

Comment From: jorisvandenbossche

Perhaps if we put the function signature on the first line of the docstring, numpydoc / sphinx will not attempt to introspect the cyfunc?

That might be an option (at least worth a try), but, that means we need to override all those inherited methods I think ?

For the attributes listing, I commented here: https://github.com/numpy/numpydoc/pull/106#issuecomment-343220139

Comment From: jorisvandenbossche

Some progress: IPython fix is merged: https://github.com/ipython/ipython/pull/10907, and I also opened a PR to sphinx (for the missing listing of attributes): https://github.com/sphinx-doc/sphinx/pull/4247 But for sphinx 1.6, the main bottleneck is still the slowdown (https://github.com/sphinx-doc/sphinx/issues/4230)

Comment From: TomAugspurger

FYI Sphinx the 1.7 beta is out https://pypi.org/project/Sphinx/1.7.0b1/

They've removed sphinx.util.compat so our vendored numpydoc and IPython sphinxext will not work.

Checking the timing now. I think Joris noted that things weren't as slow as 1.6x?

Comment From: jorisvandenbossche

Good you notice. We should make sure this time to test sphinx before they release. Last time I tried the slowdown problems were indeed solved in master: https://github.com/sphinx-doc/sphinx/issues/4230

Comment From: TomAugspurger

Some warnings / errors from a recent build with

  • sphinx 1.7
  • numpydoc master
  • IPython 6.2 dev

With the vendored versions removed:

Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/basics.rst at block ending on line 30
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/basics.rst at block ending on line 191
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/panel.py:742: FutureWarning: 
TypeError                                 Traceback (most recent call last)
   7695                 raise ValueError("transforms cannot produce "
TypeError: abs() got an unexpected keyword argument 'axis'
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/basics.rst at block ending on line 1129
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/panel.py:1056: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/basics.rst at block ending on line 1158
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/panel.py:1056: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/basics.rst at block ending on line 1169
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/panel.py:1140: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/basics.rst at block ending on line 1179
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
TypeError                                 Traceback (most recent call last)
   1007             except NotImplementedError:
TypeError: 'NoneType' object is not callable
TypeError                                 Traceback (most recent call last)
   1007             except NotImplementedError:
TypeError: 'NoneType' object is not callable
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/cookbook.rst at block ending on line 260
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/cookbook.rst at block ending on line 260
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:3395: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/dsintro.rst at block ending on line 395
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/bin/sphinx-build:1: FutureWarning: from_items is deprecated. Please use DataFrame.from_dict(dict()) instead. DataFrame.from_dict(OrderedDict()) may be used to preserve the key order.
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/dsintro.rst at block ending on line 403
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/bin/sphinx-build:2: FutureWarning: from_items is deprecated. Please use DataFrame.from_dict(dict()) instead. DataFrame.from_dict(OrderedDict()) may be used to preserve the key order.
reading sources... [ 92%] generated/pandas.errors.DtypeWarning
reading sources... [ 92%] generated/pandas.errors.EmptyDataError
reading sources... [ 92%] generated/pandas.errors.OutOfBoundsDatetime
reading sources... [ 92%] generated/pandas.errors.ParserError
reading sources... [ 92%] generated/pandas.errors.ParserWarning
reading sources... [ 92%] generated/pandas.errors.PerformanceWarning
reading sources... [ 92%] generated/pandas.errors.UnsortedIndexError
reading sources... [ 92%] generated/pandas.errors.UnsupportedFunctionCall
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/indexing.rst at block ending on line 150
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 2254
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/json/table_schema.py:75: UserWarning: Index name of 'index' is not round-trippable
  warnings.warn("Index name of 'index' is not round-trippable")
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 3323
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 3434
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 3434
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/pytables.py:3495: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 3434
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/pytables.py:708: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 3741
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/pytables.py:3495: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 3741
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/pytables.py:708: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 3761
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/pytables.py:708: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst at block ending on line 4077
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/pytables.py:708: FutureWarning: 
ModuleNotFoundError                       Traceback (most recent call last)
    173         except ImportError:
ModuleNotFoundError: No module named 'fastparquet'
ImportError                               Traceback (most recent call last)
    173         except ImportError:
    174             raise ImportError(
ImportError: fastparquet is required for parquet support
ModuleNotFoundError                       Traceback (most recent call last)
    173         except ImportError:
ModuleNotFoundError: No module named 'fastparquet'
ImportError                               Traceback (most recent call last)
    173         except ImportError:
    174             raise ImportError(
ImportError: fastparquet is required for parquet support
ModuleNotFoundError                       Traceback (most recent call last)
    173         except ImportError:
ModuleNotFoundError: No module named 'fastparquet'
ImportError                               Traceback (most recent call last)
    173         except ImportError:
    174             raise ImportError(
ImportError: fastparquet is required for parquet support
FileNotFoundError                         Traceback (most recent call last)
FileNotFoundError: [Errno 2] No such file or directory: 'example_fp.parquet'
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/release.rst at block ending on line 3242
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/release.rst at block ending on line 3242
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:3395: FutureWarning: 
Warning in /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/release.rst at block ending on line 3242
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:3395: FutureWarning: 
[IPKernelApp] WARNING | Widget Javascript not detected.  It may not be installed or enabled properly.
TypeError                                 Traceback (most recent call last)
TypeError: Invalid dtype int64 for __floordiv__
Warning in source/whatsnew/v0.23.0.txt at block ending on line 206
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/json/table_schema.py:75: UserWarning: Index name of 'index' is not round-trippable
  warnings.warn("Index name of 'index' is not round-trippable")
Warning in source/whatsnew/v0.21.0.txt at block ending on line 904
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/bin/sphinx-build:1: FutureWarning: 'pandas.tseries.converter.register' has been moved and renamed to 'pandas.plotting.register_matplotlib_converters'. 
Warning in source/whatsnew/v0.15.2.txt at block ending on line 164
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in source/whatsnew/v0.15.0.txt at block ending on line 702
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in source/whatsnew/v0.15.0.txt at block ending on line 1012
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/bin/sphinx-build:1: FutureWarning: Interpreting tuple 'by' as a list of keys, rather than a single key. Use 'by=[...]' instead of 'by=(...)'. In the future, a tuple will always mean a single key.
ValueError                                Traceback (most recent call last)
    668                 raise ValueError('Duplicated level name: "{}", assigned to '
ValueError: Duplicated level name: "baz", assigned to level 1, is already used for level 2.
Warning in source/whatsnew/v0.13.1.txt at block ending on line 162
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/bin/sphinx-build:1: FutureWarning: The reduce argument is deprecated and will be removed in a future version. You can specify result_type='reduce' to try to reduce the result to the original dimensions
Warning in source/whatsnew/v0.13.1.txt at block ending on line 162
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/bin/sphinx-build:1: FutureWarning: The reduce argument is deprecated and will be removed in a future version. You can specify result_type='reduce' to try to reduce the result to the original dimensions
Warning in source/whatsnew/v0.13.1.txt at block ending on line 241
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/panel.py:1056: FutureWarning: 
Warning in source/whatsnew/v0.13.1.txt at block ending on line 251
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/panel.py:1140: FutureWarning: 
Warning in source/whatsnew/v0.13.1.txt at block ending on line 260
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in source/whatsnew/v0.13.0.txt at block ending on line 255
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in source/whatsnew/v0.13.0.txt at block ending on line 255
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:3395: FutureWarning: 
Warning in source/whatsnew/v0.11.0.txt at block ending on line 283
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/IPython/core/interactiveshell.py:2967: FutureWarning: 
Warning in source/whatsnew/v0.11.0.txt at block ending on line 283
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:3395: FutureWarning: 
Warning in source/whatsnew/v0.11.0.txt at block ending on line 283
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:3395: FutureWarning: 
OptionError                               Traceback (most recent call last)
     82             _warn_if_deprecated(pat)
---> 83         raise OptionError('No such keys(s): {pat!r}'.format(pat=pat))
     85         raise OptionError('Pattern matched multiple keys')
OptionError: "No such keys(s): 'line_width'"
OptionError                               Traceback (most recent call last)
--> 158         raise OptionError('No such keys(s)')
OptionError: 'No such keys(s)'
NameError                                 Traceback (most recent call last)
NameError: name 'Panel4D' is not defined
NameError                                 Traceback (most recent call last)
NameError: name 'p4d' is not defined
Warning in source/whatsnew/v0.8.0.txt at block ending on line 228
Specify :okwarning: as an option in the ipython:: block to suppress this message
/Users/taugspurger/Envs/pandas-dev/bin/sphinx-build:1: FutureWarning: 'asobject' is deprecated. Use 'astype(object)' instead
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/api.rst:2518: WARNING: toctree contains reference to nonexisting document 'generated/pandas.Timestamp.offset'
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/dsintro.rst:509: WARNING: Unknown directive type "versionmodified".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.assign:38: WARNING: Unknown directive type "versionmodified".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:docstring of pandas.DataFrame.interpolate:59: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.sort_values:15: WARNING: Unknown directive type "versionmodified".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:docstring of pandas.Panel.interpolate:59: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/series.py:docstring of pandas.Series.argmax:4: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/series.py:docstring of pandas.Series.argmin:4: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/series.py:docstring of pandas.Series.asobject:5: WARNING: Inline literal start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/generic.py:docstring of pandas.Series.interpolate:59: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/groupby.py:docstring of pandas.core.groupby.DataFrameGroupBy.rank:28: WARNING: Unexpected section title or transition.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/resample.py:docstring of pandas.core.resample.Resampler.interpolate:61: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/io/json/json.py:docstring of pandas.read_json:136: WARNING: Unknown target name: "level".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/io.rst:2243: WARNING: Unknown target name: "level".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/merging.rst:155: WARNING: Inline literal start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/merging.rst:577: WARNING: Inline literal start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/merging.rst:630: WARNING: Inline literal start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/merging.rst:630: WARNING: Inline literal start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/merging.rst:630: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/merging.rst:717: WARNING: Inline literal start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/merging.rst:1197: WARNING: Inline literal start-string without end-string.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/timeseries.rst:: WARNING: Anonymous hyperlink mismatch: 1 references but 0 targets.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/visualization.rst:871: WARNING: Unknown target name: "wikipedia entry<https://en.wikipedia.org/wiki/andrews_plot>".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/visualization.rst:896: WARNING: Unknown target name: "wikipedia entry<https://en.wikipedia.org/wiki/parallel_coordinates>".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/visualization.rst:958: WARNING: Unknown target name: "wikipedia entry<https://en.wikipedia.org/wiki/correlogram>".
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/visualization.rst:1025: WARNING: Unknown target name: "radviz<https://cran.r-project.org/web/packages/radviz/>".
source/whatsnew/v0.23.0.txt:559: WARNING: Inline literal start-string without end-string.
source/whatsnew/v0.23.0.txt:559: WARNING: Inline literal start-string without end-string.
source/whatsnew/v0.23.0.txt:621: WARNING: Unknown interpreted text role "attribute".
source/whatsnew/v0.7.3.txt:: WARNING: image file not readable: _static/scatter_matrix_kde.png
source/whatsnew/v0.7.3.txt:: WARNING: image file not readable: _static/bar_plot_stacked_ex.png
source/whatsnew/v0.7.3.txt:: WARNING: image file not readable: _static/barh_plot_stacked_ex.png
checking consistency... /Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Index.holds_integer.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Index.is_type_compatible.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Index.summary.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Series.axes.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Series.imag.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Series.real.rst: WARNING: document isn't included in any toctree
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.DataFrame.to_pickle.rst:24: WARNING: Citation [R5] is not referenced.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Panel.to_pickle.rst:24: WARNING: Citation [R7] is not referenced.
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/generated/pandas.Series.to_pickle.rst:24: WARNING: Citation [R9] is not referenced.
writing output... [ 92%] generated/pandas.errors.DtypeWarning
writing output... [ 92%] generated/pandas.errors.EmptyDataError
writing output... [ 92%] generated/pandas.errors.OutOfBoundsDatetime
writing output... [ 92%] generated/pandas.errors.ParserError
writing output... [ 92%] generated/pandas.errors.ParserWarning
writing output... [ 92%] generated/pandas.errors.PerformanceWarning
writing output... [ 92%] generated/pandas.errors.UnsortedIndexError
writing output... [ 92%] generated/pandas.errors.UnsupportedFunctionCall
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/internals.rst:103: WARNING: undefined label: internals.register-accessors (if the link has no caption the label must precede a section header)
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/missing_data.rst:30: WARNING: undefined label: cookbook.missing_data (if the link has no caption the label must precede a section header)
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/doc/source/release.rst:72: WARNING: undefined label: whatsnew_0211.special (if the link has no caption the label must precede a section header)
source/whatsnew/v0.20.0.txt:392: WARNING: undefined label: style.ipynb#export-to-excel (if the link has no caption the label must precede a section header)
source/whatsnew/v0.20.0.txt:502: WARNING: undefined label: style.ipynb#subclassing (if the link has no caption the label must precede a section header)
source/whatsnew/v0.17.1.txt:60: WARNING: undefined label: style.ipynb (if the link has no caption the label must precede a section header)
source/whatsnew/v0.16.1.txt:29: WARNING: undefined label: remote_data.pandas_datareader (if the link has no caption the label must precede a section header)
source/whatsnew/v0.10.0.txt:411: WARNING: undefined label: dsintro.panel4d (if the link has no caption the label must precede a section header)
source/whatsnew/v0.6.1.txt:19: WARNING: undefined label: sparse.list (if the link has no caption the label must precede a section header)
copying images... [ 88%] savefig/errorbar_example.png
build succeeded, 50 warnings.

https://gist.github.com/b728cb6c10e0e80cd6169ac97cb37903

Comment From: TomAugspurger

I think that https://github.com/pandas-dev/pandas/pull/19657 is fixing errors like source/whatsnew/v0.7.3.txt:: WARNING: image file not readable: _static/barh_plot_stacked_ex.png

Comment From: jorisvandenbossche

I was also checking the recent travis logs, and a big part of the warnings are due to recent deprecations / removals (eg Panel started to warn more loudly). So those are not related to numpydoc/sphinx/ipython, but need some clean-up (for Panel we might want to do some general filterwarnings, if that would work for the full sphinx build)

Comment From: TomAugspurger

Things here seem to be mostly fixed. The only remaining one is things like Index.name