DOC: add DataFrame et al class docstring to api docs

[jorisvandenbossche]

closes #4790

I copied the approach of numpy: extending the autosummary class template to automatically generate all method stub files:

• https://github.com/numpy/numpy/blob/master/doc/source/_templates/autosummary/class.rst
• example output: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html

I added DataFrame, Series, Panel, Index and DatetimeIndex. Others? (eg Timestamp) Or too much?

The only issue at the moment is that normally also a list of attributes should be included, which is not the case (only a list of methods)

[jorisvandenbossche]

Example of how is DataFrame generated docstring page is looking like: http://jorisvandenbossche.github.io/example-pandas-docs/html-api-docs/generated/pandas.DataFrame.html

[jreback]

sexy!

small aside, is there a way to not include/indicate deprecated (e.g. to_wide,save,load)?

[jorisvandenbossche]

@jreback I don't think that can be directly done. In principle these could be added to undoc-member in autoclass, but these autodocs files are generated automatically with autosummary. Maybe this http://sphinx-doc.org/ext/autodoc.html#skipping-members could be a possible way.

Another possibility would be to add a docstring to eg to_wide that says DEPRECATED. Use to_panel instead so this line appears in the methods table.

[jreback]

@jorisvandenbossche this looks fine....you could add Timestamp, PeriodIndex

will have to go over the resulting doc strings to look for things that don't look right after this is merged......

@jtratner @cpcloud comments?

[jreback]

@jorisvandenbossche this an #5124 are somewhat orthogonal yes?

[cpcloud]

@jorisvandenbossche I get a bunch of errors and warnings like document isn't included in any toctree when I build the docs...

[jorisvandenbossche]

@jreback No, I think this PR and #5124 are complementary. First, #5124 just includes some extra docs on string methods to the API section. And secondly @JanSchulz created a notebook to inspect which methods are not yet included in api.rst (and this list is not included in the wiki). This is a handy list for further work on making api.rst more complete, while this PR adds some classes to api.rst and will ensure the methods of these classes have generated pages to which can be referenced from the docs. But still, it would also be good to explicitly mention them in api.rst (but that's is a lot more work).

@cpcloud Yes, indeed. That's because the attributes are for some reason not included in the generated class pages. E.g. for DataFrame (example: http://jorisvandenbossche.github.io/example-pandas-docs/html-api-docs/generated/pandas.DataFrame.html) a 'Methods' section is included, but no 'Attributes' section. So for this reason the generated attribute pages are not referenced anywhere, and therefore warnings are generated.
Why this is the case, I don't really know (normally both methods and attributes should be included), but I am looking for a solution.

[jreback]

@jorisvandenbossche ok...let us know when resolved so can merge

[jorisvandenbossche]

@jreback @cpcloud OK, worked it out! Seemed like it was because of the outdated included version of numpydoc in the sphinxext folder. So now both Attributes and Methods are included in the generated class page, and no warnings for that anymore.

I will squash when it is ready to merge.

[jorisvandenbossche]

I also added a commit to add PeriodIndex and Timestamp (just added the entry in api.rst, nothing elaborate. The section could certainly expanded).

But I get some warnings and errors when building the docs now, like WARNING: error while formatting arguments for pandas.Timestamp.to_period: <cyfunction Timestamp.to_period at 0x00000000057616C0> is not a Python function

[jtratner]

It's because it's a cython function (I guess). Might just need to write that in explicitly?

[jorisvandenbossche]

@jtratner It is a python class, but in a cython file. And I get the warning for all function that are defined there (https://github.com/pydata/pandas/blob/master/pandas/tslib.pyx#L130) Not for the inherited functions of _Timestamp or datetime.
Do you think there is a way to get rid of these warnings?

It seems that the generated docstring pages are there with the docstring rendered, but that Sphinx could not detect the signature. And it generates warnings when building the docs.

[jreback]

@jorisvandenbossche merge?

[jreback]

@jorisvandenbossche actually pls squash first

[jorisvandenbossche]

@jreback

Well, most is solved but there is still an issues. My last commit (adding Timestamp and PeriodIndex) generates warnings when building the docs because it has cython functions (and Sphinx does not play well with that, it does not find the signature).

I can squash the other commits and leave that that one for another PR?

[jreback]

@jorisvandenbossche that is fine....

[jorisvandenbossche]

@jreback done! (rebased and squashed, I will open an issue for the timestamp docs)

[jreback]

thanks