[krbdev.mit.edu #7447] Fix warnings in doc build

[Benjamin Kaduk via RT]

On Wed, 28 Nov 2012, Zhanna Tsitkova via RT wrote:

>
> On Nov 28, 2012, at 11:37 AM, Benjamin Kaduk via RT wrote:
>
>
> this commit added it as a hidden (i.e. invisible) item to the main 
> page?. what was the motivation?

No, it did not.  The commit added the license document as a hidden item to 
the *features* page.  There is no particular reason why it needed to be 
the features page, it could have been the user guide index page, or almost 
any other page other than the main index page.  (The main index page is 
unusable because Sphinx is unwilling to have partially-hidden toctrees on 
a single page.)

You ask what the motivation was for adding the license document to any 
page's toctree at all.  The answer is simple: Sphinx assumes that all 
documents will be listed in some toctree, and issues a warning at 
build-time if that invariant does not hold.  I believe that, just as we 
strive to keep our source code free of compiler warnings, we should 
endeavour to keep our documentation tree free of compiler warnings. 
Sphinx allows us to enforce this behavior with the -W argument, but we 
cannot do so while there exist warnings in the build.  Adding the features 
document to a dummy toctree is the least bad way I know of to eliminate 
this warning.  The only other options I see involve dramatically 
restructuring the way the content is presented.

Do you disagree that we should be warning-free?  Do you disagree with my 
assessment of this method being the least bad way to eliminate this 
particular warning?

>
>>
>> Why is it undesirable to have the license information in the sidebar?
>
> The better question is Why should it be there?
> The sidebar is used for easier navigation , not for static information.

I don't understand what this sentence means.  All of the documentation is 
"static information", there are merely links among it internally.

We have a link to the license information from a particular page; what 
makes having a link in the sidebar so different?  Without any links at 
all, the static information contained in the documentation would not be 
very useful...

> Yesterday we talked about adding Copyrights notice to the footer. We can 
> link it to the License or have separate tab for License or some other 
> option or leave License info in some more generalized section such as 
> MIT kern features...

If we add a copyright.rst document, it might be reasonable to include the 
license document in a (non-hidden) toctree there; I don't have a good 
sense for what a copyright.rst would look like.  I don't think the other 
options listed would involve a toctree, and therefore would still cause 
Sphinx to emit a warning at build time.


Please do note that there is a one-line patch which removes the link to 
the license document from the sidebar; I will send that out for review 
with another small patchset I have underway.

-Ben