astropy/astropy — pull request #1630 by eteq (2013-10-22 07:08:11+00:00)
Title: Make automodsumm references support multi-directory toctree paths

This fixes a really subtle bug that I discovered while investigating #1608 . It turns out that if you give a directory that has more than one level to `automodsumm` (indirectly using `automodapi`), the astropy docs fail to build (see https://travis-ci.org/eteq/astropy/jobs/12864617 ) .

The problem stems from the fact that we use some path magic to locate the ``references.txt`` files used in `wcs` and `io.fits` (and possibly other places?). But that magic isn't magical enough to deal with changes to where the `_generated` directory lives if they are multiple levels/layers. This PR fixes the problem by being a bit trickier about deriving the path to pass into the text that `atuomodsumm` generates.

It's pretty hard to figure out how to write a test for this, as it would require running sphinx on a bunch of fake docs. So hopefully it will suffice to see that the travis job I linked above fails, while this one, which includes this PR, succeeds (the one warning is mostly unrelated): https://travis-ci.org/eteq/astropy/jobs/12864916

@astrofrog - I think you wrote at least part of this originally, so you might want to glance at this and see if any of it looks odd to you