DOC: build error on to_latex

[jreback]

https://gist.github.com/changhiskhan/7159783

from @changhiskhan

[jreback]

cc @jorisvandenbossche, cc @JanSchulz

I think related to a recent change

[jankatins]

This seems to be three errors: both the ERROR: Malformed table. Column span alignment problem in table line 9. errors are pulled in via the complete addition of both Index objects in the api documentation (docs/sources/api.rst ->Index/DatetimeIndex), but the underlying error is as far as I see in np.ndarray.flags. I think the only way to remove this error (if it would not go away via a numpydoc update) is to remove the following from the API docs:

.. autosummary::
   :toctree: generated/

   Index
[...]
DatetimeIndex
-------------

.. autosummary::
   :toctree: generated/

   DatetimeIndex

The third (actually the first) could be due to some formatting problems in
pandas.core.format.docstring_to_string: the first 4 lines have one space too many

[jreback]

since Index is currently a sub-class of ndarray it picks up flags

I think this is just used internally, so could for now just provide a simple doc string for it

[jtratner]

I've seen those to_latex errors too...makes sense that it's a numpy
property. So how do we override the definition?

[jorisvandenbossche]

Yes, it are indeed three new warnings since the recent changes to the docs.
It is related to a recent change in the sense the methods are now included in the building, and before it was never built.

The to_latex is simple formatting issue, but didn't get to submit a PR.
I can't submit a PR at the moment, but it is actually a very simple change. Just adding a blank line at https://github.com/pydata/pandas/blob/master/pandas/core/frame.py#L1336 (between 1336 en 1337) should do the job.

The other two malformatted table warnings is more tricky, as you already noted, this are numpy inherited methods. So it should actually be fixed at the numpy side.

[jorisvandenbossche]

Is it possible to define the flags method in Series to call the numpy method, but providing our own docstring?

[jankatins]

wouldn't it be possible to simple set FrozenNDArray.flags.__doc__ = "" after the class is defined?

[jorisvandenbossche]

@jtratner Why do you need latex for it? It is just for the html docs?

[jtratner]

@jorisvandenbossche I don't, you're correct, I'm building it now. If flags is actually a property, then you can set the doc on it. (every property actually can take a docstring, but I believe it defaults to the getter)

[jorisvandenbossche]

@JanSchulz Seems also a good idea, but then I wouldn't set it to a empty string, but a useful short description (maybe mention numpy) because it still appears in the pandas docs.

[jtratner]

How about "internal property, do not use"? 😄

[jtratner]

Nope, can't do it:

    FrozenNDArray.flags.__doc__ = "internal property, may be removed in the future"
AttributeError: attribute '__doc__' of 'getset_descriptor' objects is not writable

[jtratner]

I thought you could exclude members...why can't we just exclude flags?

[jorisvandenbossche]

you can exclude members with autodoc, but we are using autosummary to generate the autodocs, so that's more tricky

[jtratner]

Actually, it could be nice to special case Index objects and not autosummary them, so we can actually choose what we show...