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

[cpcloud]

@jtratner Figured this out. Turns out it's the ipython directive that needs changing. I've got a PR in the works. You have to collect the traceback output in the shell class variable of IpythonDirective, then print it out using a callback mechanism that sphinx provides. So it is possible, but it took me about 2 hours of sifting through documentation to figure this out.

[jtratner]

@cpcloud one thing though - it needs to not cease building if there are errors anywhere (so you can still build local docs if you don't have R installed or something like that).

[cpcloud]

pushing to "someday" not important enough to warrant spending a lot of time on

[jorisvandenbossche]

@cpcloud @jtratner What is wrong with the suggestion @cpcloud made somewhere in the beginning of this discussion to just change all.. currentmodule:: pandas.some.submodule to .. currentmodule:: pandas?

This is a rather easy change (I could do a PR) to solve this issue.

And if we are worried with broken links, I can ensure that the old pages are still there (by keeping how it is now done in api.rst in a comment -> pages are generated, but it will not appear in the html page of api.rst).

[jtratner]

@jorisvandenbossche if you can not break old links it sounds very good to me. Heck, even if it does break old links it's probably better. Can you post an example of how it will look?

[jorisvandenbossche]

@jtratner It will look like eg the eval docstring page (http://pandas.pydata.org/pandas-docs/dev/generated/pandas.eval.html#pandas.eval), because pandas.eval is actually also pandas.computation.eval.eval but is used as top level pandas.eval

[jtratner]

Sounds good - I'm sold.