On Wed, 28 Nov 2012, Zhanna Tsitkova via RT wrote:
Show quoted text
>
> 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?
Show quoted text
>
>>
>> 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...
Show quoted text
> 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