Many documentation fixes for better Sphinx output.

14 files changed, 97 insertions, 78 deletions

diff --git a/src/mailman/model/docs/addresses.txt b/src/mailman/model/docs/addresses.txt
index 5388a3cc8..aeddb5e31 100644
--- a/src/mailman/model/docs/addresses.txt
+++ b/src/mailman/model/docs/addresses.txt
@@ -41,8 +41,8 @@ You can also create an email address object with a real name.
     >>> sorted(address.real_name for address in user_manager.addresses)
     [u'', u'Ben Person']
 
-The str() of the address is the RFC 2822 preferred originator format, while
-the repr() carries more information.
+The ``str()`` of the address is the RFC 2822 preferred originator format,
+while the ``repr()`` carries more information.
 
     >>> str(address_2)
     'Ben Person <bperson@example.com>'
@@ -149,6 +149,7 @@ Subscriptions
 
 Addresses get subscribed to mailing lists, not users.  When the address is
 subscribed, a role is specified.
+::
 
     >>> address_5 = user_manager.create_address(
     ...     'eperson@example.com', 'Elly Person')
diff --git a/src/mailman/model/docs/autorespond.txt b/src/mailman/model/docs/autorespond.txt
index ba0521a89..3a9ad01b2 100644
--- a/src/mailman/model/docs/autorespond.txt
+++ b/src/mailman/model/docs/autorespond.txt
@@ -3,11 +3,12 @@ Automatic responder
 ===================
 
 In various situations, Mailman will send an automatic response to the author
-of an email message.  For example, if someone sends a command to the -request
-address, Mailman will send a response, but to cut down on third party spam,
-the sender will only get a certain number of responses per day.
+of an email message.  For example, if someone sends a command to the
+``-request`` address, Mailman will send a response, but to cut down on third
+party spam, the sender will only get a certain number of responses per day.
 
-First, given a mailing list you need to adapt it to an IAutoResponseSet.
+First, given a mailing list you need to adapt it to an ``IAutoResponseSet``.
+::
 
     >>> mlist = create_list('test@example.com')
     >>> from mailman.interfaces.autorespond import IAutoResponseSet
@@ -17,7 +18,7 @@ First, given a mailing list you need to adapt it to an IAutoResponseSet.
     >>> verifyObject(IAutoResponseSet, response_set)
     True
 
-You can't adapt other objects to an IAutoResponseSet.
+You can't adapt other objects to an ``IAutoResponseSet``.
 
     >>> IAutoResponseSet(object())
     Traceback (most recent call last):
@@ -28,6 +29,7 @@ There are various kinds of response types.  For example, Mailman will send an
 automatic response when messages are held for approval, or when it receives an
 email command.  You can find out how many responses for a particular address
 have already been sent today.
+::
 
     >>> from mailman.interfaces.usermanager import IUserManager
     >>> from zope.component import getUtility
@@ -66,6 +68,7 @@ Let's send one more.
     2
 
 Now the day flips over and all the counts reset.
+::
 
     >>> from mailman.utilities.datetime import factory
     >>> factory.fast_forward()
@@ -92,6 +95,7 @@ You can also use the response set to get the date of the last response sent.
     datetime.date(2005, 8, 1)
 
 When another response is sent today, that becomes the last one sent.
+::
 
     >>> response_set.response_sent(address, Response.command)
     >>> response_set.last_response(address, Response.command).date_sent
diff --git a/src/mailman/model/docs/domains.txt b/src/mailman/model/docs/domains.txt
index 5673e6ee9..9fe43a5f1 100644
--- a/src/mailman/model/docs/domains.txt
+++ b/src/mailman/model/docs/domains.txt
@@ -2,7 +2,7 @@
 Domains
 =======
 
-    # The test framework starts out with an example domain, so let's delete
+..  # The test framework starts out with an example domain, so let's delete
     # that first.
     >>> from mailman.interfaces.domain import IDomainManager
     >>> from zope.component import getUtility
@@ -11,6 +11,7 @@ Domains
     <Domain example.com...>
 
 Domains are how Mailman interacts with email host names and web host names.
+::
 
     >>> from operator import attrgetter
     >>> def show_domains():
@@ -52,6 +53,7 @@ web interface for the domain.
             contact_address: postmaster@example.com>
 
 Domains can have explicit descriptions and contact addresses.
+::
 
     >>> manager.add(
     ...     'example.net',
@@ -70,6 +72,7 @@ Domains can have explicit descriptions and contact addresses.
             contact_address: postmaster@example.com>
 
 In the global domain manager, domains are indexed by their email host name.
+::
 
     >>> for domain in sorted(manager, key=attrgetter('email_host')):
     ...     print domain.email_host
@@ -87,7 +90,8 @@ In the global domain manager, domains are indexed by their email host name.
     KeyError: u'doesnotexist.com'
 
 As with a dictionary, you can also get the domain.  If the domain does not
-exist, None or a default is returned.
+exist, ``None`` or a default is returned.
+::
 
     >>> print manager.get('example.net')
     <Domain example.net, The example domain,
diff --git a/src/mailman/model/docs/languages.txt b/src/mailman/model/docs/languages.txt
index a724a0510..21143f28b 100644
--- a/src/mailman/model/docs/languages.txt
+++ b/src/mailman/model/docs/languages.txt
@@ -5,6 +5,7 @@ Languages
 Mailman is multilingual.  A language manager handles the known set of
 languages at run time, as well as enabling those languages for use in a
 running Mailman instance.
+::
 
     >>> from mailman.interfaces.languages import ILanguageManager
     >>> from zope.component import getUtility
@@ -94,6 +95,7 @@ Clearing the known languages
 ============================
 
 The language manager can forget about all the language codes it knows about.
+::
 
     >>> 'en' in mgr
     True
diff --git a/src/mailman/model/docs/listmanager.txt b/src/mailman/model/docs/listmanager.txt
index e07659066..7235049c7 100644
--- a/src/mailman/model/docs/listmanager.txt
+++ b/src/mailman/model/docs/listmanager.txt
@@ -2,10 +2,8 @@
 The mailing list manager
 ========================
 
-The IListManager is how you create, delete, and retrieve mailing list
-objects.  The Mailman system instantiates an IListManager for you based on the
-configuration variable MANAGERS_INIT_FUNCTION.  The instance is accessible
-on the global config object.
+The ``IListManager`` is how you create, delete, and retrieve mailing list
+objects.
 
     >>> from mailman.interfaces.listmanager import IListManager
     >>> from zope.component import getUtility
@@ -76,12 +74,12 @@ always get the same object back.
     >>> mlist_2 is mlist
     True
 
-If you try to get a list that doesn't existing yet, you get None.
+If you try to get a list that doesn't existing yet, you get ``None``.
 
     >>> print list_manager.get('_xtest_2@example.com')
     None
 
-You also get None if the list name is invalid.
+You also get ``None`` if the list name is invalid.
 
     >>> print list_manager.get('foo')
     None
diff --git a/src/mailman/model/docs/mailinglist.txt b/src/mailman/model/docs/mailinglist.txt
index 687f7b39c..33d681762 100644
--- a/src/mailman/model/docs/mailinglist.txt
+++ b/src/mailman/model/docs/mailinglist.txt
@@ -2,7 +2,7 @@
 Mailing lists
 =============
 
-XXX 2010-06-18 BAW: This documentation needs a lot more detail.
+.. XXX 2010-06-18 BAW: This documentation needs a lot more detail.
 
 The mailing list is a core object in Mailman.  It is uniquely identified in
 the system by its posting address, i.e. the email address you would send a
@@ -25,10 +25,11 @@ name (i.e. local part) and host name.
 Rosters
 =======
 
-Mailing list membership is represented by 'rosters'.  Each mailing list has
+Mailing list membership is represented by `rosters`.  Each mailing list has
 several rosters of members, representing the subscribers to the mailing list,
 the owners, the moderators, and so on.  The rosters are defined by a
 membership role.
+::
 
     >>> from mailman.interfaces.member import MemberRole
     >>> from mailman.testing.helpers import subscribe
diff --git a/src/mailman/model/docs/membership.txt b/src/mailman/model/docs/membership.txt
index 41660f0d2..a3782eef6 100644
--- a/src/mailman/model/docs/membership.txt
+++ b/src/mailman/model/docs/membership.txt
@@ -4,7 +4,7 @@ List memberships
 
 Users represent people in Mailman.  Users control email addresses, and rosters
 are collections of members.  A member gives an email address a role, such as
-'member', 'administrator', or 'moderator'.  Roster sets are collections of
+`member`, `administrator`, or `moderator`.  Roster sets are collections of
 rosters and a mailing list has a single roster set that contains all its
 members, regardless of that member's role.
 
@@ -180,8 +180,8 @@ It's easy to make the list administrators members of the mailing list too.
 Finding members
 ===============
 
-You can find the IMember object that is a member of a roster for a given text
-email address by using an IRoster's .get_member() method.
+You can find the ``IMember`` object that is a member of a roster for a given
+text email address by using the ``IRoster.get_member()`` method.
 
     >>> mlist.owners.get_member('aperson@example.com')
     <Member: Anne Person <aperson@example.com> on
diff --git a/src/mailman/model/docs/messagestore.txt b/src/mailman/model/docs/messagestore.txt
index aabfd55fb..3ee59129b 100644
--- a/src/mailman/model/docs/messagestore.txt
+++ b/src/mailman/model/docs/messagestore.txt
@@ -2,17 +2,17 @@
 The message store
 =================
 
-The message store is a collection of messages keyed off of Message-ID and
-X-Message-ID-Hash headers.  Either of these values can be combined with the
-message's List-Archive header to create a globally unique URI to the message
-object in the internet facing interface of the message store.  The
-X-Message-ID-Hash is the Base32 SHA1 hash of the Message-ID.
+The message store is a collection of messages keyed off of ``Message-ID`` and
+``X-Message-ID-Hash`` headers.  Either of these values can be combined with
+the message's ``List-Archive`` header to create a globally unique URI to the
+message object in the internet facing interface of the message store.  The
+``X-Message-ID-Hash`` is the Base32 SHA1 hash of the ``Message-ID``.
 
     >>> from mailman.interfaces.messages import IMessageStore
     >>> from zope.component import getUtility
     >>> message_store = getUtility(IMessageStore)
 
-If you try to add a message to the store which is missing the Message-ID
+If you try to add a message to the store which is missing the ``Message-ID``
 header, you will get an exception.
 
     >>> msg = message_from_string("""\
@@ -25,7 +25,7 @@ header, you will get an exception.
     ...
     ValueError: Exactly one Message-ID header required
 
-However, if the message has a Message-ID header, it can be stored.
+However, if the message has a ``Message-ID`` header, it can be stored.
 
     >>> msg['Message-ID'] = '<87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>'
     >>> message_store.add(msg)
@@ -42,16 +42,16 @@ However, if the message has a Message-ID header, it can be stored.
 Finding messages
 ================
 
-There are several ways to find a message given either the Message-ID or
-X-Message-ID-Hash headers.  In either case, if no matching message is found,
-None is returned.
+There are several ways to find a message given either the ``Message-ID`` or
+``X-Message-ID-Hash`` headers.  In either case, if no matching message is
+found, ``None`` is returned.
 
     >>> print message_store.get_message_by_id('nothing')
     None
     >>> print message_store.get_message_by_hash('nothing')
     None
 
-Given an existing Message-ID, the message can be found.
+Given an existing ``Message-ID``, the message can be found.
 
     >>> message = message_store.get_message_by_id(msg['message-id'])
     >>> print message.as_string()
@@ -62,7 +62,7 @@ Given an existing Message-ID, the message can be found.
     This message is very important.
     <BLANKLINE>
 
-Similarly, we can find messages by the X-Message-ID-Hash:
+Similarly, we can find messages by the ``X-Message-ID-Hash``:
 
     >>> message = message_store.get_message_by_hash(msg['x-message-id-hash'])
     >>> print message.as_string()
@@ -95,9 +95,9 @@ contains.
 Deleting messages from the store
 ================================
 
-You delete a message from the storage service by providing the Message-ID for
-the message you want to delete.  If you try to delete a Message-ID that isn't
-in the store, you get an exception.
+You delete a message from the storage service by providing the ``Message-ID``
+for the message you want to delete.  If you try to delete a ``Message-ID``
+that isn't in the store, you get an exception.
 
     >>> message_store.delete_message('nothing')
     Traceback (most recent call last):
diff --git a/src/mailman/model/docs/mlist-addresses.txt b/src/mailman/model/docs/mlist-addresses.txt
index 3f44008fb..2a021f67f 100644
--- a/src/mailman/model/docs/mlist-addresses.txt
+++ b/src/mailman/model/docs/mlist-addresses.txt
@@ -3,7 +3,7 @@ Mailing list addresses
 ======================
 
 Every mailing list has a number of addresses which are publicly available.
-These are defined in the IMailingListAddresses interface.
+These are defined in the ``IMailingListAddresses`` interface.
 
     >>> mlist = create_list('_xtest@example.com')
 
@@ -15,7 +15,7 @@ list.  This is exactly the same as the fully qualified list name.
     >>> print mlist.posting_address
     _xtest@example.com
 
-Messages to the mailing list's 'no reply' address always get discarded without
+Messages to the mailing list's `no reply` address always get discarded without
 prejudice.
 
     >>> print mlist.no_reply_address
@@ -61,7 +61,8 @@ Email confirmations
 Email confirmation messages are sent when actions such as subscriptions need
 to be confirmed.  It requires that a cookie be provided, which will be
 included in the local part of the email address.  The exact format of this is
-dependent on the VERP_CONFIRM_FORMAT configuration variable.
+dependent on the ``verp_confirm_format`` configuration variable.
+::
 
     >>> print mlist.confirm_address('cookie')
     _xtest-confirm+cookie@example.com
diff --git a/src/mailman/model/docs/pending.txt b/src/mailman/model/docs/pending.txt
index dc27b6bee..e85d8e484 100644
--- a/src/mailman/model/docs/pending.txt
+++ b/src/mailman/model/docs/pending.txt
@@ -17,8 +17,8 @@ available by adapting the list manager.
     >>> from zope.component import getUtility
     >>> pendingdb = getUtility(IPendings)
 
-The pending database can add any IPendable to the database, returning a token
-that can be used in urls and such.
+The pending database can add any ``IPendable`` to the database, returning a
+token that can be used in urls and such.
 
     >>> from mailman.interfaces.pending import IPendable
     >>> class SimplePendable(dict):
@@ -33,10 +33,10 @@ that can be used in urls and such.
     >>> len(token)
     40
 
-There's not much you can do with tokens except to 'confirm' them, which
-basically means returning the IPendable structure (as a dict) from the
-database that matches the token.  If the token isn't in the database, None is
-returned.
+There's not much you can do with tokens except to `confirm` them, which
+basically means returning the ``IPendable`` structure (as a dictionary) from
+the database that matches the token.  If the token isn't in the database,
+``None`` is returned.
 
     >>> pendable = pendingdb.confirm(bytes('missing'))
     >>> print pendable
@@ -56,7 +56,7 @@ After confirmation, the token is no longer in the database.
     None
 
 There are a few other things you can do with the pending database.  When you
-confirm a token, you can leave it in the database, or in otherwords, not
+confirm a token, you can leave it in the database, or in other words, not
 expunge it.
 
     >>> event_1 = SimplePendable(type='one')
diff --git a/src/mailman/model/docs/registration.txt b/src/mailman/model/docs/registration.txt
index abc7f2c93..050a4d0f3 100644
--- a/src/mailman/model/docs/registration.txt
+++ b/src/mailman/model/docs/registration.txt
@@ -7,10 +7,10 @@ The only thing they must supply is an email address, although there is
 additional information they may supply.  All registered email addresses must
 be verified before Mailman will send them any list traffic.
 
-The IUserManager manages users, but it does so at a fairly low level.
+The ``IUserManager`` manages users, but it does so at a fairly low level.
 Specifically, it does not handle verifications, email address syntax validity
-checks, etc.  The IRegistrar is the interface to the object handling all this
-stuff.
+checks, etc.  The ``IRegistrar`` is the interface to the object handling all
+this stuff.
 
     >>> from mailman.interfaces.registrar import IRegistrar
     >>> from zope.component import getUtility
@@ -76,9 +76,9 @@ Register an email address
 =========================
 
 Registration of an unknown address creates nothing until the confirmation step
-is complete.  No IUser or IAddress is created at registration time, but a
-record is added to the pending database, and the token for that record is
-returned.
+is complete.  No ``IUser`` or ``IAddress`` is created at registration time,
+but a record is added to the pending database, and the token for that record
+is returned.
 
     >>> token = registrar.register(mlist, 'aperson@example.com', 'Anne Person')
     >>> check_token(token)
@@ -161,12 +161,12 @@ appear in a URL in the body of the message.
     >>> sent_token == token
     True
 
-The same token will appear in the From header.
+The same token will appear in the ``From`` header.
 
     >>> items[0].msg['from'] == 'alpha-confirm+' + token + '@example.com'
     True
 
-It will also appear in the Subject header.
+It will also appear in the ``Subject`` header.
 
     >>> items[0].msg['subject'] == 'confirm ' + token
     True
@@ -178,8 +178,8 @@ token and uses that to confirm the pending registration.
     >>> registrar.confirm(token)
     True
 
-Now, there is an IAddress in the database matching the address, as well as an
-IUser linked to this address.  The IAddress is verified.
+Now, there is an ``IAddress`` in the database matching the address, as well as
+an ``IUser`` linked to this address.  The ``IAddress`` is verified.
 
     >>> found_address = user_manager.get_address('aperson@example.com')
     >>> found_address
@@ -247,7 +247,9 @@ Discarding
 ==========
 
 A confirmation token can also be discarded, say if the user changes his or her
-mind about registering.  When discarded, no IAddress or IUser is created.
+mind about registering.  When discarded, no ``IAddress`` or ``IUser`` is
+created.
+::
 
     >>> token = registrar.register(mlist, 'eperson@example.com', 'Elly Person')
     >>> check_token(token)
@@ -270,6 +272,7 @@ Registering a new address for an existing user
 When a new address for an existing user is registered, there isn't too much
 different except that the new address will still need to be verified before it
 can be used.
+::
 
     >>> dperson = user_manager.create_user(
     ...     'dperson@example.com', 'Dave Person')
@@ -310,9 +313,9 @@ confirm method will just return False.
     >>> registrar.confirm(bytes('no token'))
     False
 
-Likewise, if you try to confirm, through the IUserRegistrar interface, a token
-that doesn't match a registration event, you will get None.  However, the
-pending event matched with that token will still be removed.
+Likewise, if you try to confirm, through the ``IUserRegistrar`` interface, a
+token that doesn't match a registration event, you will get ``None``.
+However, the pending event matched with that token will still be removed.
 
     >>> from mailman.interfaces.pending import IPendable
     >>> from zope.interface import implements
diff --git a/src/mailman/model/docs/requests.txt b/src/mailman/model/docs/requests.txt
index 8cd027297..6cca8f602 100644
--- a/src/mailman/model/docs/requests.txt
+++ b/src/mailman/model/docs/requests.txt
@@ -35,6 +35,7 @@ Mailing list centric
 
 A set of requests are always related to a particular mailing list, so given a
 mailing list you need to get its requests object.
+::
 
     >>> from mailman.interfaces.requests import IListRequests, IRequests
     >>> from zope.component import getUtility
@@ -203,10 +204,10 @@ For the next section, we first clean up all the current requests.
 Application support
 ===================
 
-There are several higher level interfaces available in the mailman.app package
-which can be used to hold messages, subscription, and unsubscriptions.  There
-are also interfaces for disposing of these requests in an application specific
-and consistent way.
+There are several higher level interfaces available in the ``mailman.app``
+package which can be used to hold messages, subscription, and unsubscriptions.
+There are also interfaces for disposing of these requests in an application
+specific and consistent way.
 
     >>> from mailman.app import moderator
 
@@ -237,6 +238,7 @@ this case, we won't include any additional metadata.
     True
 
 We can also hold a message with some additional metadata.
+::
 
     # Delete the Message-ID from the previous hold so we don't try to store
     # collisions in the message storage.
@@ -336,6 +338,7 @@ re-added to the message store).  When handling a message, we can tell the
 moderator interface to also preserve a copy, essentially telling it not to
 delete the message from the storage.  First, without the switch, the message
 is deleted.
+::
 
     >>> msg = message_from_string("""\
     ... From: aperson@example.org
@@ -374,6 +377,7 @@ the message store after disposition.
 Orthogonal to preservation, the message can also be forwarded to another
 address.  This is helpful for getting the message into the inbox of one of the
 moderators.
+::
 
     # Set a new Message-ID from the previous hold so we don't try to store
     # collisions in the message storage.
@@ -678,6 +682,7 @@ The admin message is sent to the moderators.
     version             : 3
 
 Frank Person is now a member of the mailing list.
+::
 
     >>> member = mlist.members.get_member('fperson@example.org')
     >>> member
@@ -704,7 +709,9 @@ Holding unsubscription requests
 
 Some lists, though it is rare, require moderator approval for unsubscriptions.
 In this case, only the unsubscribing address is required.  Like subscriptions,
-unsubscription holds can send the list's moderators an immediate notification.
+unsubscription holds can send the list's moderators an immediate
+notification.
+::
 
     >>> mlist.admin_immed_notify = False
     >>> from mailman.interfaces.member import MemberRole
@@ -776,6 +783,7 @@ subscribed.
 
 The request can be rejected, in which case a message is sent to the member,
 and the person remains a member of the mailing list.
+::
 
     >>> moderator.handle_unsubscription(mlist, id_6, Action.reject,
     ...     'This list is a prison.')
diff --git a/src/mailman/model/docs/usermanager.txt b/src/mailman/model/docs/usermanager.txt
index 856221952..a6bd4fed2 100644
--- a/src/mailman/model/docs/usermanager.txt
+++ b/src/mailman/model/docs/usermanager.txt
@@ -2,10 +2,7 @@
 The user manager
 ================
 
-The IUserManager is how you create, delete, and manage users.  The Mailman
-system instantiates an IUserManager for you based on the configuration
-variable MANAGERS_INIT_FUNCTION.  The instance is accessible on the global
-config object.
+The ``IUserManager`` is how you create, delete, and manage users.
 
     >>> from mailman.interfaces.usermanager import IUserManager
     >>> from zope.component import getUtility
@@ -16,9 +13,10 @@ Creating users
 ==============
 
 There are several ways you can create a user object.  The simplest is to
-create a 'blank' user by not providing an address or real name at creation
+create a `blank` user by not providing an address or real name at creation
 time.  This user will have an empty string as their real name, but will not
 have a password.
+::
 
     >>> from mailman.interfaces.user import IUser
     >>> from zope.interface.verify import verifyObject
@@ -103,10 +101,10 @@ longer available through the user manager iterator.
 Finding users
 =============
 
-You can ask the user manager to find the IUser that controls a particular
+You can ask the user manager to find the ``IUser`` that controls a particular
 email address.  You'll get back the original user object if it's found.  Note
-that the .get_user() method takes a string email address, not an IAddress
-object.
+that the ``.get_user()`` method takes a string email address, not an
+``IAddress`` object.
 
     >>> address = list(user_4.addresses)[0]
     >>> found_user = user_manager.get_user(address.address)
@@ -116,7 +114,7 @@ object.
     True
 
 If the address is not in the user database or does not have a user associated
-with it, you will get None back.
+with it, you will get ``None`` back.
 
     >>> print user_manager.get_user('zperson@example.com')
     None
diff --git a/src/mailman/model/docs/users.txt b/src/mailman/model/docs/users.txt
index bb0301772..b36c250f9 100644
--- a/src/mailman/model/docs/users.txt
+++ b/src/mailman/model/docs/users.txt
@@ -133,7 +133,9 @@ Users have preferences, but these preferences have no default settings.
     receive_own_postings : None
     delivery_mode        : None
 
-Some of these preferences are booleans and they can be set to True or False.
+Some of these preferences are booleans and they can be set to ``True`` or
+``False``.
+::
 
     >>> from mailman.interfaces.languages import ILanguageManager
     >>> getUtility(ILanguageManager).add('it', 'iso-8859-1', 'Italian')
@@ -158,6 +160,7 @@ Subscriptions
 
 Users know which mailing lists they are subscribed to, regardless of
 membership role.
+::
 
     >>> user_1.link(address_1)
     >>> sorted(address.address for address in user_1.addresses)
@@ -201,8 +204,4 @@ membership role.
     zperson@example.org xtest_2@example.com MemberRole.owner
 
 
-Cross references
-================
-
 .. _`usermanager.txt`: usermanager.html
-