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

2 files changed, 9 insertions, 3 deletions

diff --git a/doc/user/tkt_mgmt.rst b/doc/user/tkt_mgmt.rst
index 0ca95accdf..1d5f23701f 100644
--- a/doc/user/tkt_mgmt.rst
+++ b/doc/user/tkt_mgmt.rst
@@ -161,7 +161,9 @@ type::
     Password for david@EXAMPLE.COM: <-- [Type david's password here.]
     shell%
 
-.. note:: You cannot mix units; specifying a lifetime of 3h30m would
+.. note::
+
+          You cannot mix units; specifying a lifetime of 3h30m would
           result in an error.  Note also that most systems specify a
           maximum ticket lifetime.  If you request a longer ticket
           lifetime, it will be automatically truncated to the maximum
diff --git a/doc/user/user_commands/ksu.rst b/doc/user/user_commands/ksu.rst
index aa22c18a3c..d1a8091b2a 100644
--- a/doc/user/user_commands/ksu.rst
+++ b/doc/user/user_commands/ksu.rst
@@ -34,7 +34,9 @@ ksu is a Kerberized version of the su program that has two missions:
 one is to securely change the real and effective user ID to that of
 the target user, and the other is to create a new security context.
 
-.. note:: For the sake of clarity, all references to and attributes of
+.. note::
+
+          For the sake of clarity, all references to and attributes of
           the user invoking the program will start with "source"
           (e.g., "source user", "source cache", etc.).
 
@@ -151,7 +153,9 @@ not provided (user hit return) ksu continues in a normal mode of
 operation (the target cache will not contain the desired TGT).  If the
 wrong password is typed in, ksu fails.
 
-.. note:: During authentication, only the tickets that could be
+.. note::
+
+          During authentication, only the tickets that could be
           obtained without providing a password are cached in in the
           source cache.