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...

[jorisvandenbossche]

But maybe could also be a lot more work :-)

Maybe this could help we want to go the way of autosummary: http://sphinx-doc.org/ext/autodoc.html#skipping-members

[jtratner]

got it - well, I'd vote for blocking all the getset_descriptor methods on Index subclasses and whitelisting dtype only.

I think you can do it with something like this:

import numpy as np
getset_descriptor = type(np.ndarray.flags)

And then you can just do if isinstance(x, getset_descriptor). Won't catch properties.

[jtratner]

anyways I'm happy to go with whatever solution you two thinks makes most sense.

[jreback]

@jorisvandenbossche @jtratner anything on this one?

[jtratner]

We can fix this completely and with little effort once Index isn't an
ndarray subclass. I'm inclined to not expend effort on this for now and
then fix in 0.14

[jtratner]

Is there any way to do super with properties? That would be a simple way to fix...

[jreback]

same way as func

[jtratner]

So super(obj, type).flags? Maybe easiest to just monkey patch for docs and leave it otherwise.

[jreback]

should work

[jreback]

I think it's fine for now - lets just bump 0.14 and ref the index refactor (which will effectively close): alternatively u can just make flags not implemented error

[jtratner]

Making flags not implemented will probably cause
segfaults/crashes/Exceptions. If I can easily whip something up to monkey
patch I will.

[jtratner]

Yep, I was right, NotImplementedError causes a nice little segfault :)

On Mon, Oct 28, 2013 at 5:41 PM, Jeffrey Tratner
jeffrey.tratner@gmail.comwrote:

Making flags not implemented will probably cause
segfaults/crashes/Exceptions. If I can easily whip something up to monkey
patch I will.

[jorisvandenbossche]

So I also added a PR to address the other part of this issue (the malformed tables). This removes the docstring of the flags attribute. This is a temporary solution, until the Index is no longer a subclass of numpy ndarray (or until it is fixed in numpy itself, which could already be the case in the newest numpy because in the dev docs, the table does render in contrast to the stable docs).