Repository: pandas-dev/pandas

Issue:
DOC: build error on to_latex
https://gist.github.com/changhiskhan/7159783

from @changhiskhan 



Discussion:
cc @jorisvandenbossche, cc @JanSchulz 

I think related to a recent change

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

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

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

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.

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

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

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

@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)

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

How about "internal property, do not use"? :smile: 

Nope, can't do it:

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

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

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

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

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

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:

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

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

@jorisvandenbossche @jtratner anything on this one?

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

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

same way as func 

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

should work

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

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

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.


Resolving patch:
diff --git a/doc/source/conf.py b/doc/source/conf.py
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -246,3 +246,12 @@
                       'GH'),
             'wiki': ('https://github.com/pydata/pandas/wiki/%s',
                      'wiki ')}
+
+# remove the docstring of the flags attribute (inherited from numpy ndarray)
+# because these give doc build errors (see GH issue 5331) 
+def remove_flags_docstring(app, what, name, obj, options, lines):
+    if what == "attribute" and name.endswith(".flags"):
+        del lines[:]
+
+def setup(app):
+    app.connect("autodoc-process-docstring", remove_flags_docstring)


Test patch: