Possible bug in Sphinx?

[embray]

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 3febebd 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?

[embray]

Yup, fairly certain this is a bug in Sphinx, or at least I was able to fix it. I might be able to create a workaround as an extension...

[embray]

PR sent to Sphinx: https://bitbucket.org/birkenfeld/sphinx/pull-request/100/fixes-a-bug-with-tocdepth-and-inventory/diff

[embray]

Any comments on this? Will this conflict with #597 at all?

[astrofrog]

It looks like the sphinx pull request was merged - does this resolve the issue completely, or only partially? Is the present pull request still needed?

[embray]

The fix to Sphinx fully resolved the issue afaict. But this workaround is still necessary to work around the issue--most of us aren't using the bleeding-edge version of Sphinx.

[embray]

"this workaround is still necessary to work around the issue" Wow that was horribly tautological. Time for me to eat lunch I think.

[astrofrog]

This seems fine to me, fee free to merge.