DOC: fix API docs generation with sphinx 1.6

[jorisvandenbossche]

See discussion #16702 (comment). Pinned sphinx to 1.5* for now (#16704)

[jorisvandenbossche]

@TomAugspurger this doesn't need to be fixed for 0.20.3 I think, but just have to remember to build the docs with 1.5* then, therefore tagging it for now as 0.20.3.

[jorisvandenbossche]

Running the api docs locally with latest sphinx 1.6.5. Some observations:

• reading the api generated pages is fast
• We get a bunch of "WARNING: toctree references unknown document 'generated/pandas.DataFrame.blocks'" warnings, but not for every attribute/method. But I do not yet see a clear pattern (eg for DataFrame it warns for blocks, columns, empty', index, is_copy, ix, style)
• it seems it is the writing of the pages that is really slow (as @TomAugspurger already noted somewhere before). In the progress output you can clearly see that each generated docstring page takes a noticeble 0.5 à 1.5 seconds to write (and since we have many of those pages ...)

[jorisvandenbossche]

Regarding the extra warnings: the methods/attributes for which we get a new warning all seem to be methods/attributes that are not listed somewhere in the api.rst page.
So it seems that for some reason the 'hack' in the class template to include a commented autosummary toctree to include all methods/attributes there is no longer working or not including those specific methods/attributes.

For the slowdown I opened an issue on sphinx: sphinx-doc/sphinx#4230

[jorisvandenbossche]

Again about the warnings, I was a bit too quick: after reading there is indeed only a limited number of warnings (as explained above), but after writing many warnings for all methods/attributes like ":: WARNING: toctree contains reference to nonexisting document 'generated/pandas.Timestamp.week' "