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

8 files changed, 75 insertions, 24 deletions

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index c15042b139..6fee6166f0 100644
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -306,6 +306,7 @@ Options:
         Associates a ticket policy to the Kerberos principal.
 
     .. note::
+
         - The **containerdn** and **linkdn** options cannot be
           specified with the **dn** option.
         - If the *dn* or *containerdn* options are not specified while
diff --git a/doc/admin/admin_commands/krb5kdc.rst b/doc/admin/admin_commands/krb5kdc.rst
index 62afca4ee6..f5b37bca38 100644
--- a/doc/admin/admin_commands/krb5kdc.rst
+++ b/doc/admin/admin_commands/krb5kdc.rst
@@ -72,7 +72,9 @@ will relay SIGHUP signals to the worker subprocesses, and will
 terminate the worker subprocess if the it is itself terminated or if
 any other worker process exits.
 
-.. note:: On operating systems which do not have *pktinfo* support,
+.. note::
+
+          On operating systems which do not have *pktinfo* support,
           using worker processes will prevent the KDC from listening
           for UDP packets on network interfaces created after the KDC
           starts.
diff --git a/doc/admin/conf_files/kadm5_acl.rst b/doc/admin/conf_files/kadm5_acl.rst
index 4a8e0741e0..ffebe90bb7 100644
--- a/doc/admin/conf_files/kadm5_acl.rst
+++ b/doc/admin/conf_files/kadm5_acl.rst
@@ -25,7 +25,9 @@ ignored.  Lines containing ACL entries have the format:
 
     principal  permissions  [target_principal  [restrictions] ]
 
-.. note:: Line order in the ACL file is important.  The first matching entry
+.. note::
+
+          Line order in the ACL file is important.  The first matching entry
           will control access for an actor principal on a target principal.
 
 *principal*
@@ -88,6 +90,7 @@ ignored.  Lines containing ACL entries have the format:
     which is allowed due to that ACL line.
 
 .. warning::
+
     If the kadmind ACL file is modified, the kadmind daemon needs to be
     restarted for changes to take effect.
 
diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst
index 4da8d936f2..7631431051 100644
--- a/doc/admin/conf_files/kdc_conf.rst
+++ b/doc/admin/conf_files/kdc_conf.rst
@@ -491,7 +491,9 @@ administrative server will be appended to the file
 PKINIT options
 --------------
 
-.. note:: The following are pkinit-specific options.  These values may
+.. note::
+
+          The following are pkinit-specific options.  These values may
           be specified in [kdcdefaults] as global defaults, or within
           a realm-specific subsection of [realms].  Also note that a
           realm-specific value over-rides, does not add to, a generic
diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index 5dbbfa49b4..6911f5c69a 100644
--- a/doc/admin/conf_files/krb5_conf.rst
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -724,7 +724,9 @@ built-in modules exist for these interfaces:
 PKINIT options
 --------------
 
-.. note:: The following are PKINIT-specific options.  These values may
+.. note::
+
+          The following are PKINIT-specific options.  These values may
           be specified in [libdefaults] as global defaults, or within
           a realm-specific subsection of [libdefaults], or may be
           specified as realm-specific values in the [realms] section.
diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index e2acb94c4c..a110d21351 100644
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -179,7 +179,9 @@ To change a principal's password use the :ref:`kadmin(1)`
    :start-after:  _change_password:
    :end-before: _change_password_end:
 
-.. note:: Password changes through kadmin are subject to the same
+.. note::
+
+          Password changes through kadmin are subject to the same
           password policies as would apply to password changes through
           :ref:`kpasswd(1)`.
 
@@ -217,7 +219,9 @@ To delete a policy, use the kadmin **delete_policy** command.
    :start-after:  _delete_policy:
    :end-before: _delete_policy_end:
 
-.. note:: You must cancel the policy from *all* principals before
+.. note::
+
+          You must cancel the policy from *all* principals before
           deleting it.  The *delete_policy* command will fail if the policy
           is in use by any principals.
 
@@ -270,7 +274,9 @@ Privileges
 Administrative privileges for the Kerberos database are stored in the
 file :ref:`kadm5.acl(5)`.
 
-.. note:: A common use of an admin instance is so you can grant
+.. note::
+
+          A common use of an admin instance is so you can grant
           separate permissions (such as administrator access to the
           Kerberos database) to a separate Kerberos principal. For
           example, the user ``joeadmin`` might have a principal for
@@ -373,7 +379,9 @@ To load a single principal, either replacing or updating the database:
      shell%
 
 
-.. note:: If the database file exists, and the *-update* flag was not
+.. note::
+
+          If the database file exists, and the *-update* flag was not
           given, *kdb5_util* will overwrite the existing database.
 
 Using kdb5_util to upgrade a master KDC from krb5 1.1.x:
@@ -390,7 +398,9 @@ The use of old-kdb-dump.ov for an extra dump and load is necessary
 to preserve per-principal policy information, which is not included in
 the default dump format of krb5 1.1.x.
 
-.. note:: Using kdb5_util to dump and reload the principal database is
+.. note::
+
+          Using kdb5_util to dump and reload the principal database is
           only necessary when upgrading from versions of krb5 prior
           to 1.2.0---newer versions will use the existing database as-is.
 
@@ -646,14 +656,18 @@ would run the following commands on the KDCs in both realms::
     Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
     kadmin:
 
-.. note:: Even if most principals in a realm are generally created
+.. note::
+
+          Even if most principals in a realm are generally created
           with the **requires_preauth** flag enabled, this flag is not
           desirable on cross-realm authentication keys because doing
           so makes it impossible to disable preauthentication on a
           service-by-service basis.  Disabling it as in the example
           above is recommended.
 
-.. note:: It is very important that these principals have good
+.. note::
+
+          It is very important that these principals have good
           passwords.  MIT recommends that TGT principal passwords be
           at least 26 characters of random ASCII text.
 
@@ -678,7 +692,9 @@ database as well as the new key.  For example::
 
     kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
 
-.. warning:: After issuing this command, the old key is still valid
+.. warning::
+
+             After issuing this command, the old key is still valid
              and is still vulnerable to (for instance) brute force
              attacks.  To completely retire an old key or encryption
              type, run the kadmin **purgekeys** command to delete keys
diff --git a/doc/admin/install_kdc.rst b/doc/admin/install_kdc.rst
index 3d0d0f1f44..77d78e14d4 100644
--- a/doc/admin/install_kdc.rst
+++ b/doc/admin/install_kdc.rst
@@ -16,6 +16,7 @@ one of the slaves if necessary (see :ref:`switch_master_slave`).  This
 installation procedure is based on that recommendation.
 
 .. warning::
+
     - The Kerberos system relies on the availability of correct time
       information.  Ensure that the master and all slave KDCs have
       properly synchronized clocks.
@@ -34,7 +35,9 @@ Install and configure the master KDC
 Install Kerberos either from the OS-provided packages or from the
 source (See :ref:`do_build`).
 
-.. note:: For the purpose of this document we will use the following
+.. note::
+
+          For the purpose of this document we will use the following
           names::
 
              kerberos.mit.edu    - master KDC
@@ -131,7 +134,9 @@ An example kdc.conf file::
 Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of
 your Kerberos realm and server respectively.
 
-.. note:: You have to have write permission on the target directories
+.. note::
+
+          You have to have write permission on the target directories
           (these directories must exist) used by **database_name**,
           **key_stash_file**, and **acl_file**.
 
@@ -144,7 +149,9 @@ Create the KDC database
 You will use the :ref:`kdb5_util(8)` command on the master KDC to
 create the Kerberos database and the optional :ref:`stash_definition`.
 
-.. note:: If you choose not to install a stash file, the KDC will
+.. note::
+
+          If you choose not to install a stash file, the KDC will
           prompt you for the master key each time it starts up.  This
           means that the KDC will not be able to start automatically,
           such as after a system reboot.
@@ -251,7 +258,9 @@ do so, type::
 
 Each server daemon will fork and run in the background.
 
-.. note:: Assuming you want these daemons to start up automatically at
+.. note::
+
+          Assuming you want these daemons to start up automatically at
           boot time, you can add them to the KDC's ``/etc/rc`` or
           ``/etc/inittab`` file.  You need to have a
           :ref:`stash_definition` in order to do this.
@@ -280,7 +289,9 @@ Install the slave KDCs
 
 You are now ready to start configuring the slave KDCs.
 
-.. note:: Assuming you are setting the KDCs up so that you can easily
+.. note::
+
+          Assuming you are setting the KDCs up so that you can easily
           switch the master KDC with one of the slaves, you should
           perform each of these steps on the master KDC as well as the
           slave KDCs, unless these instructions specify otherwise.
@@ -358,7 +369,9 @@ the KDCs::
     host/kerberos.mit.edu@ATHENA.MIT.EDU
     host/kerberos-1.mit.edu@ATHENA.MIT.EDU
 
-.. note:: If you expect that the master and slave KDCs will be
+.. note::
+
+          If you expect that the master and slave KDCs will be
           switched at some point of time, list the host principals
           from all participating KDC servers in kpropd.acl files on
           all of the KDCs.  Otherwise, you only need to list the
@@ -408,7 +421,9 @@ following example::
 You will need a script to dump and propagate the database. The
 following is an example of a Bourne shell script that will do this.
 
-.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc``
+.. note::
+
+          Remember that you need to replace ``/usr/local/var/krb5kdc``
           with the name of the KDC state directory.
 
 ::
@@ -442,13 +457,17 @@ Propagation failed?
 
 .. _prop_failed_start:
 
-.. error:: kprop: No route to host while connecting to server
+.. error::
+
+           kprop: No route to host while connecting to server
 
 Make sure that the hostname of the slave (as given to kprop) is
 correct, and that any firewalls beween the master and the slave allow
 a connection on port 754.
 
-.. error:: kprop: Connection refused in call to connect while opening
+.. error::
+
+           kprop: Connection refused in call to connect while opening
            connection
 
 If the slave is intended to run kpropd out of inetd, make sure that
@@ -457,7 +476,9 @@ to be restarted or sent a SIGHUP to recognize the new configuration.
 If the slave is intended to run kpropd in standalone mode, make sure
 that it is running.
 
-.. error:: kprop: Server rejected authentication while authenticating
+.. error::
+
+           kprop: Server rejected authentication while authenticating
            to server
 
 Make sure that:
diff --git a/doc/admin/troubleshoot.rst b/doc/admin/troubleshoot.rst
index 7dc25795d8..3e1cbd64f5 100644
--- a/doc/admin/troubleshoot.rst
+++ b/doc/admin/troubleshoot.rst
@@ -31,10 +31,14 @@ of the :ref:`kvno(1)` command::
 List
 ----
 
-.. error:: KDC has no support for encryption type while getting
+.. error::
+
+           KDC has no support for encryption type while getting
            initial credentials
 
-.. error:: credential verification failed: KDC has no support for
+.. error::
+
+           credential verification failed: KDC has no support for
            encryption type
 
 This most commonly happens when trying to use a principal with only