astropy/astropy — pull request #595 by iguananaut (2012-12-27 18:37:23+00:00)
Title: Possible bug in Sphinx?

Assigning this to 0.2 for now since I just created this bug, but I'm not sure what the quickest resolution will be.

If you look at the latest docs (http://docs.astropy.org/en/latest/) you'll see that in 3febebdbd5841410109a09129f1d1b3f98845740 I added a link on the index to "What's New in Astropy 0.2". I added it as a heading just so that it pops out more, but the problem is that now it shows up under the page's table of contents on the sidebar as "whatsnew-0.2". Really it shouldn't show up there at all.

According to the Sphinx documentation I should be able to add `:tocdepth: 2` to the top of the page to control this, and indeed that works as expected and should solve the problem. Except when I do that and rebuild the docs I get a bunch of these warnings:

```
/bray/sc1/root/src/astropy/astropy/docs/changelog.rst:: WARNING: document isn't included in any toctree
/bray/sc1/root/src/astropy/astropy/docs/configs/index.rst:: WARNING: document isn't included in any toctree
/bray/sc1/root/src/astropy/astropy/docs/coordinates/index.rst:: WARNING: document isn't included in any toctree
/bray/sc1/root/src/astropy/astropy/docs/cosmology/index.rst:: WARNING: document isn't included in any toctree
/bray/sc1/root/src/astropy/astropy/docs/creditsandlicense.rst:: WARNING: document isn't included in any toctree
/bray/sc1/root/src/astropy/astropy/docs/development/building_packaging.rst:: WARNING: document isn't included in any toctree
<...and so on...>
```

This makes no sense, as those pages are included in TOCs on the main index, and those TOCs are still being rendered just fine. So I think that has to be a bug.

In the meantime, does anyone have any better ideas for displaying this link in such a way that it pops out a bit?