astropy/astropy — pull request #1826 by kbarbary (2013-11-25 18:54:05+00:00)
Title: Show correct user-facing module paths in documentation stub pages

Motivation
----------------

I've run into the problem recently that I point a user to an API documentation page, say
http://astropy.readthedocs.org/en/stable/api/astropy.stats.funcs.sigma_clip.html
to pick a random example, and the user sees the path to the function as being `astropy.stats.funcs.sigma_clip` rather than `astropy.stats.sigma_clip`. As a result, it is not entirely clear what is the correct way to import the function or class. This problem exists throughout the documentation: in most cases we import module objects into a higher-level namespace and intend for users to only use the higher-level namespace.

What it does
-------------------
This PR changes the automodsumm sphinx extension so that built stub pages have the API that users should use. It does this by using the `.. currentmodule::` directive and then supplying the `.. autosummary::` directive with the local, rather than fully qualified object names. A built set of docs can be found [here](http://www.hep.anl.gov/kbarbary/astropy-docs/). See for instance http://www.hep.anl.gov/kbarbary/astropy-docs/api/astropy.stats.sigma_clip.html

Related changes
------------------------
In conjunction, there are a few other necessary changes:

* Include a patched version of the `viewcode` extension, as the current version in sphinx fails to link to code correctly under this usage of autosummary. The patch comes from this issue in the sphinx issue tracker: https://bitbucket.org/birkenfeld/sphinx/issue/623/ so hopefully it will be merged into Sphinx proper, at which point this patched version can be removed from astropy.

* I had to change an automodsumm table in the `convolution/kernels.rst` documentation to an explicit autosummary table. It should be possible to simply do
```python
.. automodsumm:: astropy.convolution
:classes-only:
```
there, but that wasn't working and I couldn't figure out why not. Help making that work would be appreciated.

* Third, I noticed I missing `__all__` in convolution/core.py. The omission has been resulting in AstropyUserWarning being included in the API docs for convolution, which was not intended.

Remaining issues
--------------------------
There are some remaining issues before this PR is merged:

* Class attribute stubs are no longer linked to their source code, but I don't think this is a big loss. This is probably part of the `viewcode` bug that isn't fixed by the patch.
* The base classes in model docs are no longer linked correctly. I looked at the numpy/scipy docs to see their solution to this problem. It seems to be simply omitting the line telling you the base classes. I think thats probably OK to do as this info can be found easily by clicking to the source code.
* There are some scattered object references in the docs that will need to be fixed. I can do that if we want to move forward with this PR.
* We probably want to update the part of automodapi that creates inheritance diagrams as well.