Make resources.rst more useful to non-devs

Reorder the IRC channel listing so #kerberos is first.  (Developers
form a smaller part of our audience for this documentation set.)
Remove some details that are available on the wiki and not of interest
to non-developers.

Add a pointer to the wiki.

Fix minor grammar errors in Archives.

(cherry picked from commit 4e0d270faad7fabd773cb159b8cb8e03adb19462)

ticket: 7482
version_fixed: 1.11
status: resolved
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.

(cherry picked from commit 8bff1e50c28b6f11b771add7bd7d4a57419a567b)

ticket: 7469
version_fixed: 1.11
status: resolved
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/

(cherry picked from commit 81fc0331cdf8a41b346daaee32977d76ab645139)

ticket: 7466
version_fixed: 1.11
status: resolved
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.

(cherry picked from commit b017751b711dfd70c8735f655a51e5ff860af49b)

ticket: 7467
version_fixed: 1.11
status: resolved
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.

(cherry picked from commit 9031b739fc4f9e4215e537855a853d2134a69ba9)

ticket: 7470
version_fixed: 1.11
status: resolved
Fix typo

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

(cherry picked from commit db26cd1b6f422c20c062385e0daeb8c95137428d)

ticket: 7471
version_fixed: 1.11
status: resolved
Don't use $(RM) in src/doc/Makefile.in

We allow these rules to be used in an unconfigured tree, and some
makes do not supply a value for RM by default.

(cherry picked from commit 3f7394c1440f7526bc6f008f841b438d84411f3d)

ticket: 7492
version: 1.11
status: resolved
Do not document unused symbols

The macro KRB5_KEYUSAGE_PA_REFERRAL was defined in an early revision
of draft-ietf-krb-wg-kerberos-referrals but did not make it into
RFC 6806.  We retain the definition so as to not break code implementing
the early draft, but need not document it.

Likewise, the krb5_octet_data structure and krb5_free_octet_data routine
are marked as having been originally introduced for PKINIT and "Do not
use this."  They are in fact unused, and should not be documented, but
the actual definitions must remain for compatibility.

(cherry picked from commit 6e6364f7c7613a6b8002f0f64864e7d34acea8be)

ticket: 7489
version_fixed: 1.11
status: resolved
Update comments for RFC 3244 kpasswd extensions

Remove the inaccurate comments "unused" and replace them with
more useful representations of what they mean.

(cherry picked from commit f2cec6d908a8b15908f4de199540e5ad3486882b)

ticket: 7490
version_fixed: 1.11
status: resolved
Make building docs easier in an unconfigured tree

Instead of requiring the user to specify srcdir, top_srcdir, PYTHON,
and possibly more in the future, make an 'htmlsrc' target that does so
for them.

This also lets us do the clean in the same step, so that only one
command is required of the user.

(cherry picked from commit f6ef297fe537de3712fce751bad8a597ef32e0ed)

ticket: 7491
version_fixed: 1.11
status: resolved
Make sphinx warnings fatal for doc build

We currently do not have any warnings.  Let us keep it that way by
making warnings fatal in maintainer-mode (and configurable on the
buildslaves).  Using sphinx-build -W also causes errors to be reported
in the exit status and picked up by make, which is quite useful.

In order to allow the build bot to use -W but end-users to not use it,
SPHINX_ARGS must be passed on the command line; it cannot be set by
the convenience target 'htmlsrc'.  Document this.

(cherry picked from commit 7b6758a09f92ccc386022bcc86e3a5fea472fdce)

ticket: 7468
version_fixed: 1.11
status: resolved
Regenerate checked-in man pages

Pick up changes to kadmin.rst and krb5_conf.rst adding cross-references
for account lockout and detailing parameter expansion for keytab
and credentials cache names in krb5.conf

(cherry picked from commit 26481ee22377a46badbbf4bbdd8ae04265057205)

ticket: 7494
version_fixed: 1.11
status: resolved
Document API for getting anonymous tickets

In init_creds.rst, document how to get anonymous credentials from an
application.

(cherry picked from commit 9973812776fc69bc5fb8e3c7f85784cb295625f0)

ticket: 7496
version_fixed: 1.11
status: resolved