make docs reflect API usage not the fully qualified name

[cpcloud]

minor issue, but would be nice for consistency

http://pandas.pydata.org/pandas-docs/stable/generated/pandas.io.parsers.read_table.html#pandas.io.parsers.read_table

shows it as pandas.io.parsers.read_table but it should be used as pandas.read_table and that's how it should appear

this could be a simple sphinx reference label change

FWIW this would probably invalidate a lot of links on SO

[jtratner]

why not do both so we don't invalidate old links?

[cpcloud]

not exactly sure what you mean...make it appear as above and then have a shadowed link? we would have to do this for every object in the API, not sure if there's an automated way to do this...

[jtratner]

Maybe we could try using autodoc extension (if we're not already doing it)? I thought sphinx actually compiled and executed modules to determine elements - so I'd imagine it could handle documenting at both the top level namespace and in the subpackages - how would it know the difference?

e.g.

.. autodoc:: pandas
   :members:
   :exclude-members: np, datetime, util, algos, io, version

(exclude-members would have everything we don't want documented but still is in the toplevel pandas namespace)

[cpcloud]

The API usage docs are taken from the .. currentmodule:: pandas.io.parser: bits, but if i write .. currentmodule:: pandas then it will appear as pandas.whatever_is_in_the_top_level.

[jtratner]

Right, so maybe you could have two copies of that file? (one for toplevel pandas and one for pandas.io.parser?) Or a separate file describing the toplevel namespace and the internals for compatibility?

That said, not terrible to break some links.

[jtratner]

@cpcloud on a related note - is there a way to make sphinx exit non-zero if there are errors during the doc build? it'd be nice to add the doc building to Travis, but it looks like it looks like it doesn't actually exit non-zero if there are build errors...

[cpcloud]

try this http://sphinx-doc.org/invocation.html#cmdoption-sphinx-build-W

[jtratner]

@cpcloud good call. wish it had an option to keep building and then error out at the end though (then you could see alll the build errors...)

[cpcloud]

yeah i think failing fast tho is good there then you don't have to wait for everything

[jtratner]

@cpcloud I tried playing around with it. passing -W to sphinx-build means that it errors out if it can't find a necessary component (like latex), but it doesn't cause it to stop if it encounters errors when executing doc examples :-/

[cpcloud]

Well that's annoying....hmm i might ask on SO if I can come up with a reasonable minimal example....sphinx-build requires quite a bit of infrastructure... OTOH maybe i can just say check out the pandas repo....although i anticipate many many downvotes if ido that

[jtratner]

@cpcloud here's a minimal example:

"""
Some function docstring.

.. ipython::
   import nampy as np
"""

Should fail because nampy doesn't exist.

Or with a doctest

"""
Some function docstring

>>> 1 + {}
"""

We would want it to exit 1 because the example would fail

[cpcloud]

and all this time i thought it was called numpy... 😄

[jtratner]

@cpcloud you might want to double check that it doesn't fail for you before asking on SO. I think I didn't see it, but I'm not sure. Don't have time to set up sphinx to check this on my own computer right now tho :P

[cpcloud]

I think erroring out here is probably just making the embedded ipython shell exit when it raises...going to try it