krb5 commit: Reformat RST to avoid sphinx warnings
Benjamin Kaduk
kaduk at MIT.EDU
Mon Dec 10 13:15:34 EST 2012
https://github.com/krb5/krb5/commit/8bff1e50c28b6f11b771add7bd7d4a57419a567b
commit 8bff1e50c28b6f11b771add7bd7d4a57419a567b
Author: Ben Kaduk <kaduk at mit.edu>
Date: Wed Nov 28 14:19:43 2012 -0500
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
doc/README | 4 +++
doc/admin/admin_commands/kadmin_local.rst | 1 +
doc/admin/admin_commands/krb5kdc.rst | 4 ++-
doc/admin/conf_files/kadm5_acl.rst | 5 +++-
doc/admin/conf_files/kdc_conf.rst | 4 ++-
doc/admin/conf_files/krb5_conf.rst | 4 ++-
doc/admin/database.rst | 32 +++++++++++++++++-----
doc/admin/install_kdc.rst | 41 ++++++++++++++++++++++-------
doc/admin/troubleshoot.rst | 8 ++++-
doc/appdev/gssapi.rst | 12 ++++++--
doc/basic/date_format.rst | 2 +
doc/basic/stash_file_def.rst | 4 ++-
doc/plugindev/profile.rst | 4 ++-
doc/tools/func_document.tmpl | 3 ++
doc/user/tkt_mgmt.rst | 4 ++-
doc/user/user_commands/ksu.rst | 8 ++++-
16 files changed, 108 insertions(+), 32 deletions(-)
diff --git a/doc/README b/doc/README
index 8bb1c47..a49d110 100644
--- a/doc/README
+++ b/doc/README
@@ -67,3 +67,7 @@ We use the following conventions:
to indicate optional parameters). If immediately following one kind
of inline markup with another or putting inline markup next to
punctuation, you may need to use "\ " as a dummy separator.
+
+* For directives that take a content block (e.g., note, error, and
+ warning), leave a blank line before the content block (after any
+ arguments or options that may be present).
diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index c15042b..6fee616 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 62afca4..f5b37bc 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 4a8e074..ffebe90 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 4da8d93..7631431 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 5dbbfa4..6911f5c 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 e2acb94..a110d21 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 at 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 at 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 3d0d0f1..77d78e1 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 at ATHENA.MIT.EDU
host/kerberos-1.mit.edu at 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 7dc2579..3e1cbd6 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
diff --git a/doc/appdev/gssapi.rst b/doc/appdev/gssapi.rst
index 29c06b5..a8c731b 100644
--- a/doc/appdev/gssapi.rst
+++ b/doc/appdev/gssapi.rst
@@ -145,16 +145,22 @@ the default keytab. If the input name contains both a *service* and a
*hostname*, clients will be allowed to authenticate to any host-based
principal for the named service and hostname, regardless of realm.
-.. note:: If a *hostname* is specified, it will be canonicalized
+.. note::
+
+ If a *hostname* is specified, it will be canonicalized
using forward name resolution, and possibly also using
reverse name resolution depending on the value of the
**rdns** variable in :ref:`libdefaults`.
-.. note:: If the **ignore_acceptor_hostname** variable in
+.. note::
+
+ If the **ignore_acceptor_hostname** variable in
:ref:`libdefaults` is enabled, then *hostname* will be
ignored even if one is specified in the input name.
-.. note:: In MIT krb5 versions prior to 1.10, and in Heimdal's
+.. note::
+
+ In MIT krb5 versions prior to 1.10, and in Heimdal's
implementation of the krb5 mechanism, an input name with
just a *service* is treated like an input name of
``service at localhostname``, where *localhostname* is the
diff --git a/doc/basic/date_format.rst b/doc/basic/date_format.rst
index bb89251..f9460fe 100644
--- a/doc/basic/date_format.rst
+++ b/doc/basic/date_format.rst
@@ -23,6 +23,7 @@ Here *N* denotes a number, *d* - days, *h* - hours, *m* - minutes,
*s* - seconds.
.. note::
+
The time interval should not exceed 2147483647 seconds.
Examples::
@@ -133,6 +134,7 @@ Abbreviations used in this document
| *z* : numeric time zone;
.. note::
+
- If the date specification contains spaces, you may need to
enclose it in double quotes;
- All keywords are case-insensitive.
diff --git a/doc/basic/stash_file_def.rst b/doc/basic/stash_file_def.rst
index cd6cca4..256e2c2 100644
--- a/doc/basic/stash_file_def.rst
+++ b/doc/basic/stash_file_def.rst
@@ -17,7 +17,9 @@ The file should not be part of any backup of the machine, unless
access to the backup data is secured as tightly as access to the
master password itself.
-.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up.
+.. 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.
diff --git a/doc/plugindev/profile.rst b/doc/plugindev/profile.rst
index 671d4c1..7dbfdbf 100644
--- a/doc/plugindev/profile.rst
+++ b/doc/plugindev/profile.rst
@@ -6,7 +6,9 @@ configuration information is obtained by the Kerberos library and
applications. For a detailed description of the profile interface,
see the header file ``<profile.h>``.
-.. note:: The profile interface does not follow the normal conventions
+.. note::
+
+ The profile interface does not follow the normal conventions
for MIT krb5 pluggable interfaces, because it is part of a
lower-level component of the krb5 library.
diff --git a/doc/tools/func_document.tmpl b/doc/tools/func_document.tmpl
index b9b63d1..4986058 100644
--- a/doc/tools/func_document.tmpl
+++ b/doc/tools/func_document.tmpl
@@ -82,11 +82,13 @@ $function.long_description
#if $function.warn_description is not None
.. warning::
+
$function.warn_description
#end if
#if $function.notes_description is not None
.. note::
+
$function.notes_description
#end if
@@ -94,6 +96,7 @@ $function.long_description
#if $function.version_num is not None
.. note::
+
$function.version_num
#end if
diff --git a/doc/user/tkt_mgmt.rst b/doc/user/tkt_mgmt.rst
index 0ca95ac..1d5f237 100644
--- a/doc/user/tkt_mgmt.rst
+++ b/doc/user/tkt_mgmt.rst
@@ -161,7 +161,9 @@ type::
Password for david at 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 aa22c18..d1a8091 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.
More information about the cvs-krb5
mailing list