Docs/automodapi extension - #115

I get a couple of errors:

/Users/tom/dropbox/code/development/astropy_forks/eteq/docs/development/testguide.rst:43: ERROR: Error in "note" directive:
invalid option block.

.. note::
    This method of running the tests defaults to the version of `py.test` that
    is bundled with Astropy. To use the locally-installed version, you should
    either change the `use_system_pytest` configuration option to "True" (see
    :doc:`../../configs`) or the `py.test` method describe below.
/Users/tom/dropbox/code/development/astropy_forks/eteq/docs/development/testguide.rst:138: ERROR: Error in "note" directive:
invalid option block.

.. note::
    This method of running the tests defaults to the version of `py.test` that
    is bundled with Astropy. To use the locally-installed version, you should
    either change the `use_system_pytest` configuration option to "True" (see
    :doc:`../../configs`) or the `py.test` method describe above.

There is also a wcs-related error, but I'll report that in a different ticket as it was there before your changes.

@astrofrog - that's very odd... I don't see these errors at all. What version of Sphinx do you have? I'm also confused as to how this could possibly trigger errors in testguide.rst, because that's not modified in this pull request...

Ok, this error does indeed occur in master using Sphinx 1.1.2, so you can ignore it for this pull request. I fixed it directly in master in 5d338b3.

@astrofrog - huh, that fix is very strange - I don't understand why this would have fixed your error... especially given that I built these docs with the same version of sphinx (1.1.2) and they built without complaint. Ah well, if it fixed it, it fixed it, and no harm done!

I'm not sure either, but it seems it interpreted :doc: at the start of the indented line to be an option directive. Maybe I was using a developer version of sphinx.

Hmm... well, the latest development version seems to currently be at the 1.1.2 release, so unless you were using an older developer version, that should be it. Very strange! But I guess it doesn't matter if it's working for both of us now.

One thing I just realized, though - if I build the docs using python setup.py build_sphinx, it places the generated files in a _generated directory in the source root, instead of in docs. I'll have to figure out how to fix this before we can merge this.

Minor point I just noticed while working -- docs/_generated should be added to .gitignore.

@astrofrog and @mdboom
I think this is now working the way I had in mind. There are tests, but the coverage isn't that good because a lot of it has to be done in a sphinx context. But If you look at the configuration documentation section, you can see basically what this produces now (there's also a lot more options).

One of the new options is that it is now possible to separate out the documentation for different subpackages/modules of the module being documented. I'll start a broader discussion on the list regarding exactly how often we want to use that, but these extensions now support either way, so it shouldn't affect the PR itself.

@eteq - I seem to be getting tons of warnings about generated files: https://gist.github.com/2016457 - is this normal?

@astrofrog - That should not be happening... It looks like you tested it using build_sphinx, is that correct? I haven't tested that, mainly because I don't really trust build_sphinx until #171 is implemented. If you instead install astropy (via either setup.py install or setup.py develop), and then use make html in the docs directory, do the warnings go away?

Also, can you look for the _generated directory and tell me if the files it's looking for are actually there? One of the big subtleties I had to fix in this PR involves convincing all the :toctree: <dir> entires to all go into the same directory, so if the _generated directory is in the wrong place, that might explain it.

@eteq - ah, I got confused, I thought build_sphinx was the way to go (since the docs require the build documentation). Doing build then make html does work better, and produces the tables with the links to the generated API pages. There is still an error in the middle of make html but it doesn't seem to stop the rest from working:

<autodoc>:0: ERROR: Unexpected indentation.

(see full log here: https://gist.github.com/2020724)

By the way, I've just committed a fix for the wrap before the colon in 'Parameters :' - see 7b530ab

@eteq - could you push your branch to staging so I can run the tests?

@astrofrog - I just pushed to my staging branch - see https://github.com/eteq/astropy/tree/staging.

The <autodoc>:0: ERROR: Unexpected indentation. Is pre-existing - if you go back to master you'll see it's present there as well. I've seen these errors like this before, but they are painful to debug because for some reason autodoc sometimes gets very confused when its used with numpydoc... I generally find them by incrementally removing .rst files until I find which removal that fix it. But I'll do that separate from this pull request given that it's not directly related.

And great that you found a fix for the 'Parameters :' problem! That had been really annoying for some time.

@astrofrog , @mdboom , as far as you're concerned, can I merge this?

I don't have time to review the code in detail, but it looks like it's working fine, and producing nice output! So from my point of view, this is ready to go.

Yep -- I'm in the same camp with @astrofrog.

Ok, sounds good - merging!