Reformat RST to avoid sphinx warnings

Old versions of docutils will see inline markup (e.g., :ref:`foo`)
at the beginning of a line in the content of a directive block
and attempt to interpret that markup as options or arguments
to the directive.  RST intended as inline markup (as opposed to
modifying the behavior of the directive) will not be interpretable
in this context, and causes Sphinx to emit a warning.

Work around this behavior by always leaving a blank line before
the content of a directive block, forcing it to be interpreted
as content and not options or arguments.

The buggy behavior was only encountered in note environments, but
for consistency of style, also reformat warning and error blocks.

Note the new style constraint in doc/README.

ticket: 7469 (new)
title: doc buildslave generates sphinx warnings
tags: pullup
target_version: 1.11
Do not generate unused parts of toctree

Our css only displays up to depth 3 of the toctree, partially
because the API reference content explodes at depth 4 and that would
not be pretty to see in the sidebar.  However, we would previously
always generate HTML for the full toctree and hide parts with CSS.
For the apiref, this proved to be about 65k per html file, and we
have one html file per function/type/macro.

Limit the depth of the toctree that gets generated to save on space
in the release tarball.

Unfortunately, there seems to be a Sphinx bug wherein the toctree
will only be generated to depth 1 for a document at a depth greater
than the maxdepth of the toctree, so the sidebar table of contents
on individual apiref pages will just be the toplevel toctree.
This issue is being tracked at
https://bitbucket.org/birkenfeld/sphinx/issue/1046/

ticket: 7466 (new)
tags: pullup
target_version: 1.11
Do not include hidden files in the sidebar

We play games with hidden toctrees in the RST source to avoid
Sphinx warnings; make sure that they do not affect the rendered
output.

ticket: 7467 (new)
tags: pullup
target_version: 1.11
Note notice.txt's dependency on version.py

This dependency has been in effect since the notice build was changed
to use the main conf.py, due to its unconditional execfile('version.py').
Adding another conditional in conf.py seems to add needless complication,
it is easier to just note the dependency in the Makefile and carry on.

ticket: 7470 (new)
title: NOTICE build has unnoted dependency on version.py
tags: pullup
target_version: 1.11
Fix typo

We do not have any files with extension "rxt".

ticket: 7471 (new)
title: typo in exclude_patterns for notice build
tags: pullup
target_version: 1.11
Fix various integer issues

In kdc_util.c and spnego_mech.c, error returns from ASN.1 length
functions could be ignored because they were assigned to unsigned
values.  In spnego_mech.c, two buffer size checks could be rewritten
to reduce the likelihood of pointer overflow.  In dump.c and
kdc_preauth.c, calloc() could be used to simplify the code and avoid
multiplication overflow.  In pkinit_clnt.c, the wrong value was
checked for a null result from malloc(), and the code could be
simplified.

Reported by Nickolai Zeldovich <nickolai@csail.mit.edu>.

ticket: 7488
Document principal name interactions with DNS