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

[Zhanna Tsitkova via RT]

On Nov 28, 2012, at 11:37 AM, Benjamin Kaduk via RT wrote:

> On Wed, 28 Nov 2012, Zhanna Tsitkova via RT wrote:
> 
>> [kaduk at MIT.EDU - Tue Nov 27 18:02:34 2012]:
>> 
>>> 
>>> Remove last "document not in toctree" warnings
>>> 
>>> There were two of them, for notice.rst and mitK5license.rst.
>>> The former is included in the latter, which is linked to from
>>> the mitK5features document but not listed in a table of contents
>>> otherwise.  Includes are processed unconditionally, so we can
>>> add notice.rst to the exclude_patterns array (formerly unused_docs)
>>> and its content will still be included.
>>> 
>>> If we attempt to do the same for mitK5license.rst, it is not processed
>>> at all, and the attempt to link to it will fail.  Instead, put a dummy
>>> table of contents in the mitK5features document (which links to the
>>> license document), with the "hidden" attribute.  This satisfies the
>>> Sphinx need to know where all the input documents are without changing
>>> the displayed table of contents.
>>> 
>>> https://github.com/krb5/krb5/commit/b358b505be4502a71495ce58b8444027121726ee
>>> Author: Ben Kaduk <kaduk at mit.edu>
>>> Commit: b358b505be4502a71495ce58b8444027121726ee
>>> Branch: master
>>> doc/conf.py           |    1 +
>>> doc/mitK5features.rst |    5 +++++
>>> 2 files changed, 6 insertions(+), 0 deletions(-)
>> 
>> Now MIT Kerberos License information appears in the sidebar which is undesirable behavior.
> 
> Hmm, this may be a Sphinx bug, I'll try to look and see.

this commit added it as a hidden (i.e. invisible) item to the main page…. what was the motivation?
 
> 
> 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. 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...

> 
> -Ben
> 
> _______________________________________________
> krb5-bugs mailing list
> krb5-bugs at mit.edu
> https://mailman.mit.edu/mailman/listinfo/krb5-bugs