Merged revisions 74868,74877-74878 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74868 | georg.brandl | 2009-09-17 12:23:02 +0200 (Do, 17 Sep 2009) | 2 lines

  String values should be shown with quotes, to avoid confusion with constants.
........
  r74877 | georg.brandl | 2009-09-17 18:26:06 +0200 (Do, 17 Sep 2009) | 1 line

  Remove duplicate doc of enable/disable_interspersed_args.
........
  r74878 | georg.brandl | 2009-09-17 19:14:04 +0200 (Do, 17 Sep 2009) | 1 line

  Make the optparse doc style a bit more standard: use standard description units for attrs/methods/etc., and use the correct referencing roles.
........

1 files changed, 519 insertions, 471 deletions

diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index 05aa378..523079f 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -7,14 +7,14 @@
 .. sectionauthor:: Greg Ward <gward@python.net>
 
 
-``optparse`` is a more convenient, flexible, and powerful library for parsing
-command-line options than the old :mod:`getopt` module.  ``optparse`` uses a more declarative
-style of command-line parsing: you create an instance of :class:`OptionParser`,
-populate it with options, and parse the command line. ``optparse`` allows users
-to specify options in the conventional GNU/POSIX syntax, and additionally
-generates usage and help messages for you.
+:mod:`optparse` is a more convenient, flexible, and powerful library for parsing
+command-line options than the old :mod:`getopt` module.  :mod:`optparse` uses a
+more declarative style of command-line parsing: you create an instance of
+:class:`OptionParser`, populate it with options, and parse the command
+line. :mod:`optparse` allows users to specify options in the conventional
+GNU/POSIX syntax, and additionally generates usage and help messages for you.
 
-Here's an example of using ``optparse`` in a simple script::
+Here's an example of using :mod:`optparse` in a simple script::
 
    from optparse import OptionParser
    [...]
@@ -32,11 +32,11 @@ on the command-line, for example::
 
    <yourscript> --file=outfile -q
 
-As it parses the command line, ``optparse`` sets attributes of the ``options``
-object returned by :meth:`parse_args` based on user-supplied command-line
-values.  When :meth:`parse_args` returns from parsing this command line,
-``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
-``False``.  ``optparse`` supports both long and short options, allows short
+As it parses the command line, :mod:`optparse` sets attributes of the
+``options`` object returned by :meth:`parse_args` based on user-supplied
+command-line values.  When :meth:`parse_args` returns from parsing this command
+line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
+``False``.  :mod:`optparse` supports both long and short options, allows short
 options to be merged together, and allows options to be associated with their
 arguments in a variety of ways.  Thus, the following command lines are all
 equivalent to the above example::
@@ -51,7 +51,7 @@ Additionally, users can run one of  ::
    <yourscript> -h
    <yourscript> --help
 
-and ``optparse`` will print out a brief summary of your script's options::
+and :mod:`optparse` will print out a brief summary of your script's options::
 
    usage: <yourscript> [options]
 
@@ -82,10 +82,10 @@ Terminology
 ^^^^^^^^^^^
 
 argument
-   a string entered on the command-line, and passed by the shell to ``execl()`` or
-   ``execv()``.  In Python, arguments are elements of ``sys.argv[1:]``
-   (``sys.argv[0]`` is the name of the program being executed).  Unix shells also
-   use the term "word".
+   a string entered on the command-line, and passed by the shell to ``execl()``
+   or ``execv()``.  In Python, arguments are elements of ``sys.argv[1:]``
+   (``sys.argv[0]`` is the name of the program being executed).  Unix shells
+   also use the term "word".
 
    It is occasionally desirable to substitute an argument list other than
    ``sys.argv[1:]``, so you should read "argument" as "an element of
@@ -93,14 +93,14 @@ argument
    ``sys.argv[1:]``".
 
 option
-   an argument used to supply extra information to guide or customize the execution
-   of a program.  There are many different syntaxes for options; the traditional
-   Unix syntax is a hyphen ("-") followed by a single letter, e.g. ``"-x"`` or
-   ``"-F"``.  Also, traditional Unix syntax allows multiple options to be merged
-   into a single argument, e.g.  ``"-x -F"`` is equivalent to ``"-xF"``.  The GNU
-   project introduced ``"--"`` followed by a series of hyphen-separated words, e.g.
-   ``"--file"`` or ``"--dry-run"``.  These are the only two option syntaxes
-   provided by :mod:`optparse`.
+   an argument used to supply extra information to guide or customize the
+   execution of a program.  There are many different syntaxes for options; the
+   traditional Unix syntax is a hyphen ("-") followed by a single letter,
+   e.g. ``"-x"`` or ``"-F"``.  Also, traditional Unix syntax allows multiple
+   options to be merged into a single argument, e.g.  ``"-x -F"`` is equivalent
+   to ``"-xF"``.  The GNU project introduced ``"--"`` followed by a series of
+   hyphen-separated words, e.g.  ``"--file"`` or ``"--dry-run"``.  These are the
+   only two option syntaxes provided by :mod:`optparse`.
 
    Some other option syntaxes that the world has seen include:
 
@@ -117,15 +117,16 @@ option
    * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,
      ``"/file"``
 
-   These option syntaxes are not supported by :mod:`optparse`, and they never will
-   be.  This is deliberate: the first three are non-standard on any environment,
-   and the last only makes sense if you're exclusively targeting VMS, MS-DOS,
-   and/or Windows.
+   These option syntaxes are not supported by :mod:`optparse`, and they never
+   will be.  This is deliberate: the first three are non-standard on any
+   environment, and the last only makes sense if you're exclusively targeting
+   VMS, MS-DOS, and/or Windows.
 
 option argument
-   an argument that follows an option, is closely associated with that option, and
-   is consumed from the argument list when that option is. With :mod:`optparse`,
-   option arguments may either be in a separate argument from their option::
+   an argument that follows an option, is closely associated with that option,
+   and is consumed from the argument list when that option is. With
+   :mod:`optparse`, option arguments may either be in a separate argument from
+   their option::
 
       -f foo
       --file foo
@@ -135,25 +136,26 @@ option argument
       -ffoo
       --file=foo
 
-   Typically, a given option either takes an argument or it doesn't. Lots of people
-   want an "optional option arguments" feature, meaning that some options will take
-   an argument if they see it, and won't if they don't.  This is somewhat
-   controversial, because it makes parsing ambiguous: if ``"-a"`` takes an optional
-   argument and ``"-b"`` is another option entirely, how do we interpret ``"-ab"``?
-   Because of this ambiguity, :mod:`optparse` does not support this feature.
+   Typically, a given option either takes an argument or it doesn't. Lots of
+   people want an "optional option arguments" feature, meaning that some options
+   will take an argument if they see it, and won't if they don't.  This is
+   somewhat controversial, because it makes parsing ambiguous: if ``"-a"`` takes
+   an optional argument and ``"-b"`` is another option entirely, how do we
+   interpret ``"-ab"``?  Because of this ambiguity, :mod:`optparse` does not
+   support this feature.
 
 positional argument
    something leftover in the argument list after options have been parsed, i.e.
-   after options and their arguments have been parsed and removed from the argument
-   list.
+   after options and their arguments have been parsed and removed from the
+   argument list.
 
 required option
    an option that must be supplied on the command-line; note that the phrase
    "required option" is self-contradictory in English.  :mod:`optparse` doesn't
-   prevent you from implementing required options, but doesn't give you much help
-   at it either.  See ``examples/required_1.py`` and ``examples/required_2.py`` in
-   the :mod:`optparse` source distribution for two ways to implement required
-   options with :mod:`optparse`.
+   prevent you from implementing required options, but doesn't give you much
+   help at it either.  See ``examples/required_1.py`` and
+   ``examples/required_2.py`` in the :mod:`optparse` source distribution for two
+   ways to implement required options with :mod:`optparse`.
 
 For example, consider this hypothetical command-line::
 
@@ -282,8 +284,9 @@ that's rarely necessary: by default it uses ``sys.argv[1:]``.)
 * ``args``, the list of positional arguments leftover after parsing options
 
 This tutorial section only covers the four most important option attributes:
-:attr:`action`, :attr:`!type`, :attr:`dest` (destination), and :attr:`help`. Of
-these, :attr:`action` is the most fundamental.
+:attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
+(destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
+most fundamental.
 
 
 .. _optparse-understanding-option-actions:
@@ -294,9 +297,9 @@ Understanding option actions
 Actions tell :mod:`optparse` what to do when it encounters an option on the
 command line.  There is a fixed set of actions hard-coded into :mod:`optparse`;
 adding new actions is an advanced topic covered in section
-:ref:`optparse-extending-optparse`. Most actions tell
-:mod:`optparse` to store a value in some variable---for example, take a string
-from the command line and store it in an attribute of ``options``.
+:ref:`optparse-extending-optparse`.  Most actions tell :mod:`optparse` to store
+a value in some variable---for example, take a string from the command line and
+store it in an attribute of ``options``.
 
 If you don't specify an option action, :mod:`optparse` defaults to ``store``.
 
@@ -334,7 +337,7 @@ Also, there's no explicit action, since the default is ``store``.
 
 Let's parse another fake command-line.  This time, we'll jam the option argument
 right up against the option: since ``"-n42"`` (one argument) is equivalent to
-``"-n 42"`` (two arguments), the code  ::
+``"-n 42"`` (two arguments), the code ::
 
    (options, args) = parser.parse_args(["-n42"])
    print(options.num)
@@ -386,16 +389,16 @@ Other actions
 
 Some other actions supported by :mod:`optparse` are:
 
-``store_const``
+``"store_const"``
    store a constant value
 
-``append``
+``"append"``
    append this option's argument to a list
 
-``count``
+``"count"``
    increment a counter by one
 
-``callback``
+``"callback"``
    call a specified function
 
 These are covered in section :ref:`optparse-reference-guide`, Reference Guide
@@ -454,8 +457,8 @@ Generating help
 
 :mod:`optparse`'s ability to generate help and usage text automatically is
 useful for creating user-friendly command-line interfaces.  All you have to do
-is supply a :attr:`help` value for each option, and optionally a short usage
-message for your whole program.  Here's an OptionParser populated with
+is supply a :attr:`~Option.help` value for each option, and optionally a short
+usage message for your whole program.  Here's an OptionParser populated with
 user-friendly (documented) options::
 
    usage = "usage: %prog [options] arg1 arg2"
@@ -499,12 +502,12 @@ help message:
      usage = "usage: %prog [options] arg1 arg2"
 
   :mod:`optparse` expands ``"%prog"`` in the usage string to the name of the
-  current program, i.e. ``os.path.basename(sys.argv[0])``.  The expanded string is
-  then printed before the detailed option help.
+  current program, i.e. ``os.path.basename(sys.argv[0])``.  The expanded string
+  is then printed before the detailed option help.
 
   If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
-  default: ``"usage: %prog [options]"``, which is fine if your script doesn't take
-  any positional arguments.
+  default: ``"usage: %prog [options]"``, which is fine if your script doesn't
+  take any positional arguments.
 
 * every option defines a help string, and doesn't worry about line-wrapping---
   :mod:`optparse` takes care of wrapping lines and making the help output look
@@ -518,29 +521,29 @@ help message:
   Here, "MODE" is called the meta-variable: it stands for the argument that the
   user is expected to supply to :option:`-m`/:option:`--mode`.  By default,
   :mod:`optparse` converts the destination variable name to uppercase and uses
-  that for the meta-variable.  Sometimes, that's not what you want---for example,
-  the :option:`--filename` option explicitly sets ``metavar="FILE"``, resulting in
-  this automatically-generated option description::
+  that for the meta-variable.  Sometimes, that's not what you want---for
+  example, the :option:`--filename` option explicitly sets ``metavar="FILE"``,
+  resulting in this automatically-generated option description::
 
      -f FILE, --filename=FILE
 
-  This is important for more than just saving space, though: the manually written
-  help text uses the meta-variable "FILE" to clue the user in that there's a
-  connection between the semi-formal syntax "-f FILE" and the informal semantic
-  description "write output to FILE". This is a simple but effective way to make
-  your help text a lot clearer and more useful for end users.
+  This is important for more than just saving space, though: the manually
+  written help text uses the meta-variable "FILE" to clue the user in that
+  there's a connection between the semi-formal syntax "-f FILE" and the informal
+  semantic description "write output to FILE". This is a simple but effective
+  way to make your help text a lot clearer and more useful for end users.
 
 * options that have a default value can include ``%default`` in the help
   string---\ :mod:`optparse` will replace it with :func:`str` of the option's
   default value.  If an option has no default value (or the default value is
   ``None``), ``%default`` expands to ``none``.
 
-When dealing with many options, it is convenient to group these
-options for better help output.  An :class:`OptionParser` can contain
-several option groups, each of which can contain several options.
+When dealing with many options, it is convenient to group these options for
+better help output.  An :class:`OptionParser` can contain several option groups,
+each of which can contain several options.
 
-Continuing with the parser defined above, adding an
-:class:`OptionGroup` to a parser is easy::
+Continuing with the parser defined above, adding an :class:`OptionGroup` to a
+parser is easy::
 
     group = OptionGroup(parser, "Dangerous Options",
                         "Caution: use these options at your own risk.  "
@@ -595,17 +598,17 @@ How :mod:`optparse` handles errors
 
 There are two broad classes of errors that :mod:`optparse` has to worry about:
 programmer errors and user errors.  Programmer errors are usually erroneous
-calls to ``parser.add_option()``, e.g. invalid option strings, unknown option
-attributes, missing option attributes, etc.  These are dealt with in the usual
-way: raise an exception (either ``optparse.OptionError`` or :exc:`TypeError`) and
-let the program crash.
+calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
+option attributes, missing option attributes, etc.  These are dealt with in the
+usual way: raise an exception (either :exc:`optparse.OptionError` or
+:exc:`TypeError`) and let the program crash.
 
 Handling user errors is much more important, since they are guaranteed to happen
 no matter how stable your code is.  :mod:`optparse` can automatically detect
 some user errors, such as bad option arguments (passing ``"-n 4x"`` where
 :option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end
 of the command line, where :option:`-n` takes an argument of any type).  Also,
-you can call ``parser.error()`` to signal an application-defined error
+you can call :func:`OptionParser.error` to signal an application-defined error
 condition::
 
    (options, args) = parser.parse_args()
@@ -634,7 +637,7 @@ Or, where the user fails to pass a value at all::
 
 :mod:`optparse`\ -generated error messages take care always to mention the
 option involved in the error; be sure to do the same when calling
-``parser.error()`` from your application code.
+:func:`OptionParser.error` from your application code.
 
 If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
 you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
@@ -682,49 +685,51 @@ Reference Guide
 Creating the parser
 ^^^^^^^^^^^^^^^^^^^
 
-The first step in using :mod:`optparse` is to create an OptionParser instance::
+The first step in using :mod:`optparse` is to create an OptionParser instance.
 
-   parser = OptionParser(...)
+.. class:: OptionParser(...)
 
-The OptionParser constructor has no required arguments, but a number of optional
-keyword arguments.  You should always pass them as keyword arguments, i.e. do
-not rely on the order in which the arguments are declared.
+   The OptionParser constructor has no required arguments, but a number of
+   optional keyword arguments.  You should always pass them as keyword
+   arguments, i.e. do not rely on the order in which the arguments are declared.
 
    ``usage`` (default: ``"%prog [options]"``)
-      The usage summary to print when your program is run incorrectly or with a help
-      option.  When :mod:`optparse` prints the usage string, it expands ``%prog`` to
-      ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you passed that keyword
-      argument).  To suppress a usage message, pass the special value
-      ``optparse.SUPPRESS_USAGE``.
+      The usage summary to print when your program is run incorrectly or with a
+      help option.  When :mod:`optparse` prints the usage string, it expands
+      ``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
+      passed that keyword argument).  To suppress a usage message, pass the
+      special value :data:`optparse.SUPPRESS_USAGE`.
 
    ``option_list`` (default: ``[]``)
       A list of Option objects to populate the parser with.  The options in
-      ``option_list`` are added after any options in ``standard_option_list`` (a class
-      attribute that may be set by OptionParser subclasses), but before any version or
-      help options. Deprecated; use :meth:`add_option` after creating the parser
-      instead.
+      ``option_list`` are added after any options in ``standard_option_list`` (a
+      class attribute that may be set by OptionParser subclasses), but before
+      any version or help options. Deprecated; use :meth:`add_option` after
+      creating the parser instead.
 
    ``option_class`` (default: optparse.Option)
       Class to use when adding options to the parser in :meth:`add_option`.
 
    ``version`` (default: ``None``)
-      A version string to print when the user supplies a version option. If you supply
-      a true value for ``version``, :mod:`optparse` automatically adds a version
-      option with the single option string ``"--version"``.  The substring ``"%prog"``
-      is expanded the same as for ``usage``.
+      A version string to print when the user supplies a version option. If you
+      supply a true value for ``version``, :mod:`optparse` automatically adds a
+      version option with the single option string ``"--version"``.  The
+      substring ``"%prog"`` is expanded the same as for ``usage``.
 
    ``conflict_handler`` (default: ``"error"``)
-      Specifies what to do when options with conflicting option strings are added to
-      the parser; see section :ref:`optparse-conflicts-between-options`.
+      Specifies what to do when options with conflicting option strings are
+      added to the parser; see section
+      :ref:`optparse-conflicts-between-options`.
 
    ``description`` (default: ``None``)
-      A paragraph of text giving a brief overview of your program.  :mod:`optparse`
-      reformats this paragraph to fit the current terminal width and prints it when
-      the user requests help (after ``usage``, but before the list of options).
-
-   ``formatter`` (default: a new IndentedHelpFormatter)
-      An instance of optparse.HelpFormatter that will be used for printing help text.
-      :mod:`optparse` provides two concrete classes for this purpose:
+      A paragraph of text giving a brief overview of your program.
+      :mod:`optparse` reformats this paragraph to fit the current terminal width
+      and prints it when the user requests help (after ``usage``, but before the
+      list of options).
+
+   ``formatter`` (default: a new :class:`IndentedHelpFormatter`)
+      An instance of optparse.HelpFormatter that will be used for printing help
+      text.  :mod:`optparse` provides two concrete classes for this purpose:
       IndentedHelpFormatter and TitledHelpFormatter.
 
    ``add_help_option`` (default: ``True``)
@@ -743,14 +748,14 @@ Populating the parser
 ^^^^^^^^^^^^^^^^^^^^^
 
 There are several ways to populate the parser with options.  The preferred way
-is by using ``OptionParser.add_option()``, as shown in section
+is by using :meth:`OptionParser.add_option`, as shown in section
 :ref:`optparse-tutorial`.  :meth:`add_option` can be called in one of two ways:
 
 * pass it an Option instance (as returned by :func:`make_option`)
 
 * pass it any combination of positional and keyword arguments that are
-  acceptable to :func:`make_option` (i.e., to the Option constructor), and it will
-  create the Option instance for you
+  acceptable to :func:`make_option` (i.e., to the Option constructor), and it
+  will create the Option instance for you
 
 The other alternative is to pass a list of pre-constructed Option instances to
 the OptionParser constructor, as in::
@@ -778,66 +783,67 @@ Each Option instance represents a set of synonymous command-line option strings,
 e.g. :option:`-f` and :option:`--file`.  You can specify any number of short or
 long option strings, but you must specify at least one overall option string.
 
-The canonical way to create an Option instance is with the :meth:`add_option`
-method of :class:`OptionParser`::
+The canonical way to create an :class:`Option` instance is with the
+:meth:`add_option` method of :class:`OptionParser`.
 
-   parser.add_option(opt_str[, ...], attr=value, ...)
+.. method:: OptionParser.add_option(opt_str[, ...], attr=value, ...)
 
-To define an option with only a short option string::
+   To define an option with only a short option string::
 
-   parser.add_option("-f", attr=value, ...)
+      parser.add_option("-f", attr=value, ...)
 
-And to define an option with only a long option string::
+   And to define an option with only a long option string::
 
-   parser.add_option("--foo", attr=value, ...)
+      parser.add_option("--foo", attr=value, ...)
 
-The keyword arguments define attributes of the new Option object.  The most
-important option attribute is :attr:`action`, and it largely determines which
-other attributes are relevant or required.  If you pass irrelevant option
-attributes, or fail to pass required ones, :mod:`optparse` raises an
-:exc:`OptionError` exception explaining your mistake.
+   The keyword arguments define attributes of the new Option object.  The most
+   important option attribute is :attr:`~Option.action`, and it largely
+   determines which other attributes are relevant or required.  If you pass
+   irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
+   raises an :exc:`OptionError` exception explaining your mistake.
 
-An option's *action* determines what :mod:`optparse` does when it encounters
-this option on the command-line.  The standard option actions hard-coded into
-:mod:`optparse` are:
+   An option's *action* determines what :mod:`optparse` does when it encounters
+   this option on the command-line.  The standard option actions hard-coded into
+   :mod:`optparse` are:
 
-``store``
-   store this option's argument (default)
+   ``"store"``
+      store this option's argument (default)
 
-``store_const``
-   store a constant value
+   ``"store_const"``
+      store a constant value
 
-``store_true``
-   store a true value
+   ``"store_true"``
+      store a true value
 
-``store_false``
-   store a false value
+   ``"store_false"``
+      store a false value
 
-``append``
-   append this option's argument to a list
+   ``"append"``
+      append this option's argument to a list
 
-``append_const``
-   append a constant value to a list
+   ``"append_const"``
+      append a constant value to a list
 
-``count``
-   increment a counter by one
+   ``"count"``
+      increment a counter by one
 
-``callback``
-   call a specified function
+   ``"callback"``
+      call a specified function
 
-:attr:`help`
-   print a usage message including all options and the documentation for them
+   ``"help"``
+      print a usage message including all options and the documentation for them
 
-(If you don't supply an action, the default is ``store``.  For this action, you
-may also supply :attr:`!type` and :attr:`dest` option attributes; see below.)
+   (If you don't supply an action, the default is ``"store"``.  For this action,
+   you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
+   attributes; see :ref:`optparse-standard-option-actions`.)
 
 As you can see, most actions involve storing or updating a value somewhere.
 :mod:`optparse` always creates a special object for this, conventionally called
-``options`` (it happens to be an instance of ``optparse.Values``).  Option
+``options`` (it happens to be an instance of :class:`optparse.Values`).  Option
 arguments (and various other values) are stored as attributes of this object,
-according to the :attr:`dest` (destination) option attribute.
+according to the :attr:`~Option.dest` (destination) option attribute.
 
-For example, when you call  ::
+For example, when you call ::
 
    parser.parse_args()
 
@@ -845,7 +851,7 @@ one of the first things :mod:`optparse` does is create the ``options`` object::
 
    options = Values()
 
-If one of the options in this parser is defined with  ::
+If one of the options in this parser is defined with ::
 
    parser.add_option("-f", "--file", action="store", type="string", dest="filename")
 
@@ -856,13 +862,97 @@ and the command-line being parsed includes any of the following::
    --file=foo
    --file foo
 
-then :mod:`optparse`, on seeing this option, will do the equivalent of  ::
+then :mod:`optparse`, on seeing this option, will do the equivalent of ::
 
    options.filename = "foo"
 
-The :attr:`!type` and :attr:`dest` option attributes are almost as important as
-:attr:`action`, but :attr:`action` is the only one that makes sense for *all*
-options.
+The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
+as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
+one that makes sense for *all* options.
+
+
+.. _optparse-option-attributes:
+
+Option attributes
+^^^^^^^^^^^^^^^^^
+
+The following option attributes may be passed as keyword arguments to
+:meth:`OptionParser.add_option`.  If you pass an option attribute that is not
+relevant to a particular option, or fail to pass a required option attribute,
+:mod:`optparse` raises :exc:`OptionError`.
+
+.. attribute:: Option.action
+
+   (default: ``"store"``)
+
+   Determines :mod:`optparse`'s behaviour when this option is seen on the
+   command line; the available options are documented :ref:`here
+   <optparse-standard-option-actions>`.
+
+.. attribute:: Option.type
+
+   (default: ``"string"``)
+
+   The argument type expected by this option (e.g., ``"string"`` or ``"int"``);
+   the available option types are documented :ref:`here
+   <optparse-standard-option-types>`.
+
+.. attribute:: Option.dest
+
+   (default: derived from option strings)
+
+   If the option's action implies writing or modifying a value somewhere, this
+   tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
+   attribute of the ``options`` object that :mod:`optparse` builds as it parses
+   the command line.
+
+.. attribute:: Option.default
+
+   The value to use for this option's destination if the option is not seen on
+   the command line.  See also :meth:`OptionParser.set_defaults`.
+
+.. attribute:: Option.nargs
+
+   (default: 1)
+
+   How many arguments of type :attr:`~Option.type` should be consumed when this
+   option is seen.  If > 1, :mod:`optparse` will store a tuple of values to
+   :attr:`~Option.dest`.
+
+.. attribute:: Option.const
+
+   For actions that store a constant value, the constant value to store.
+
+.. attribute:: Option.choices
+
+   For options of type ``"choice"``, the list of strings the user may choose
+   from.
+
+.. attribute:: Option.callback
+
+   For options with action ``"callback"``, the callable to call when this option
+   is seen.  See section :ref:`optparse-option-callbacks` for detail on the
+   arguments passed to the callable.
+
+.. attribute:: Option.callback_args
+               Option.callback_kwargs
+
+   Additional positional and keyword arguments to pass to ``callback`` after the
+   four standard callback arguments.
+
+.. attribute:: Option.help
+
+   Help text to print for this option when listing all available options after
+   the user supplies a :attr:`~Option.help` option (such as ``"--help"``).  If
+   no help text is supplied, the option will be listed without help text.  To
+   hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
+
+.. attribute:: Option.metavar
+
+   (default: derived from option strings)
+
+   Stand-in for the option argument(s) to use when printing help text.  See
+   section :ref:`optparse-tutorial` for an example.
 
 
 .. _optparse-standard-option-actions:
@@ -875,42 +965,45 @@ Most actions have several relevant option attributes which you may specify to
 guide :mod:`optparse`'s behaviour; a few have required attributes, which you
 must specify for any option using that action.
 
-* ``store`` [relevant: :attr:`!type`, :attr:`dest`, ``nargs``, ``choices``]
+* ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
+  :attr:`~Option.nargs`, :attr:`~Option.choices`]
 
   The option must be followed by an argument, which is converted to a value
-  according to :attr:`!type` and stored in :attr:`dest`.  If ``nargs`` > 1,
-  multiple arguments will be consumed from the command line; all will be converted
-  according to :attr:`!type` and stored to :attr:`dest` as a tuple.  See the
-  "Option types" section below.
+  according to :attr:`~Option.type` and stored in :attr:`~Option.dest`.  If
+  :attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
+  command line; all will be converted according to :attr:`~Option.type` and
+  stored to :attr:`~Option.dest` as a tuple.  See the
+  :ref:`optparse-standard-option-types` section.
 
-  If ``choices`` is supplied (a list or tuple of strings), the type defaults to
-  ``choice``.
+  If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
+  defaults to ``"choice"``.
 
-  If :attr:`!type` is not supplied, it defaults to ``string``.
+  If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
 
-  If :attr:`dest` is not supplied, :mod:`optparse` derives a destination from the
-  first long option string (e.g., ``"--foo-bar"`` implies ``foo_bar``). If there
-  are no long option strings, :mod:`optparse` derives a destination from the first
-  short option string (e.g., ``"-f"`` implies ``f``).
+  If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
+  from the first long option string (e.g., ``"--foo-bar"`` implies
+  ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
+  destination from the first short option string (e.g., ``"-f"`` implies ``f``).
 
   Example::
 
      parser.add_option("-f")
      parser.add_option("-p", type="float", nargs=3, dest="point")
 
-  As it parses the command line  ::
+  As it parses the command line ::
 
      -f foo.txt -p 1 -3.5 4 -fbar.txt
 
-  :mod:`optparse` will set  ::
+  :mod:`optparse` will set ::
 
      options.f = "foo.txt"
      options.point = (1.0, -3.5, 4.0)
      options.f = "bar.txt"
 
-* ``store_const`` [required: ``const``; relevant: :attr:`dest`]
+* ``"store_const"`` [required: :attr:`~Option.const`; relevant:
+  :attr:`~Option.dest`]
 
-  The value ``const`` is stored in :attr:`dest`.
+  The value :attr:`~Option.const` is stored in :attr:`~Option.dest`.
 
   Example::
 
@@ -925,29 +1018,32 @@ must specify for any option using that action.
 
      options.verbose = 2
 
-* ``store_true`` [relevant: :attr:`dest`]
+* ``"store_true"`` [relevant: :attr:`~Option.dest`]
 
-  A special case of ``store_const`` that stores a true value to :attr:`dest`.
+  A special case of ``"store_const"`` that stores a true value to
+  :attr:`~Option.dest`.
 
-* ``store_false`` [relevant: :attr:`dest`]
+* ``"store_false"`` [relevant: :attr:`~Option.dest`]
 
-  Like ``store_true``, but stores a false value.
+  Like ``"store_true"``, but stores a false value.
 
   Example::
 
      parser.add_option("--clobber", action="store_true", dest="clobber")
      parser.add_option("--no-clobber", action="store_false", dest="clobber")
 
-* ``append`` [relevant: :attr:`!type`, :attr:`dest`, ``nargs``, ``choices``]
+* ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
+  :attr:`~Option.nargs`, :attr:`~Option.choices`]
 
   The option must be followed by an argument, which is appended to the list in
-  :attr:`dest`.  If no default value for :attr:`dest` is supplied, an empty list
-  is automatically created when :mod:`optparse` first encounters this option on
-  the command-line.  If ``nargs`` > 1, multiple arguments are consumed, and a
-  tuple of length ``nargs`` is appended to :attr:`dest`.
+  :attr:`~Option.dest`.  If no default value for :attr:`~Option.dest` is
+  supplied, an empty list is automatically created when :mod:`optparse` first
+  encounters this option on the command-line.  If :attr:`~Option.nargs` > 1,
+  multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
+  is appended to :attr:`~Option.dest`.
 
-  The defaults for :attr:`!type` and :attr:`dest` are the same as for the ``store``
-  action.
+  The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
+  for the ``"store"`` action.
 
   Example::
 
@@ -963,16 +1059,19 @@ must specify for any option using that action.
 
      options.tracks.append(int("4"))
 
-* ``append_const`` [required: ``const``; relevant: :attr:`dest`]
+* ``"append_const"`` [required: :attr:`~Option.const`; relevant:
+  :attr:`~Option.dest`]
 
-  Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as
-  with ``append``, :attr:`dest` defaults to ``None``, and an empty list is
-  automatically created the first time the option is encountered.
+  Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
+  :attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
+  ``None``, and an empty list is automatically created the first time the option
+  is encountered.
 
-* ``count`` [relevant: :attr:`dest`]
+* ``"count"`` [relevant: :attr:`~Option.dest`]
 
-  Increment the integer stored at :attr:`dest`.  If no default value is supplied,
-  :attr:`dest` is set to zero before being incremented the first time.
+  Increment the integer stored at :attr:`~Option.dest`.  If no default value is
+  supplied, :attr:`~Option.dest` is set to zero before being incremented the
+  first time.
 
   Example::
 
@@ -988,27 +1087,29 @@ must specify for any option using that action.
 
      options.verbosity += 1
 
-* ``callback`` [required: ``callback``; relevant: :attr:`!type`, ``nargs``,
-  ``callback_args``, ``callback_kwargs``]
+* ``"callback"`` [required: :attr:`~Option.callback`; relevant:
+  :attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
+  :attr:`~Option.callback_kwargs`]
 
-  Call the function specified by ``callback``, which is called as  ::
+  Call the function specified by :attr:`~Option.callback`, which is called as ::
 
      func(option, opt_str, value, parser, *args, **kwargs)
 
   See section :ref:`optparse-option-callbacks` for more detail.
 
-* :attr:`help`
+* ``"help"``
 
-  Prints a complete help message for all the options in the current option parser.
-  The help message is constructed from the ``usage`` string passed to
-  OptionParser's constructor and the :attr:`help` string passed to every option.
+  Prints a complete help message for all the options in the current option
+  parser.  The help message is constructed from the ``usage`` string passed to
+  OptionParser's constructor and the :attr:`~Option.help` string passed to every
+  option.
 
-  If no :attr:`help` string is supplied for an option, it will still be listed in
-  the help message.  To omit an option entirely, use the special value
-  ``optparse.SUPPRESS_HELP``.
+  If no :attr:`~Option.help` string is supplied for an option, it will still be
+  listed in the help message.  To omit an option entirely, use the special value
+  :data:`optparse.SUPPRESS_HELP`.
 
-  :mod:`optparse` automatically adds a :attr:`help` option to all OptionParsers,
-  so you do not normally need to create one.
+  :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
+  OptionParsers, so you do not normally need to create one.
 
   Example::
 
@@ -1025,8 +1126,8 @@ must specify for any option using that action.
                        help="Input file to read data from")
      parser.add_option("--secret", help=SUPPRESS_HELP)
 
-  If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line, it
-  will print something like the following help message to stdout (assuming
+  If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line,
+  it will print something like the following help message to stdout (assuming
   ``sys.argv[0]`` is ``"foo.py"``)::
 
      usage: foo.py [options]
@@ -1039,82 +1140,14 @@ must specify for any option using that action.
   After printing the help message, :mod:`optparse` terminates your process with
   ``sys.exit(0)``.
 
-* ``version``
-
-  Prints the version number supplied to the OptionParser to stdout and exits.  The
-  version number is actually formatted and printed by the ``print_version()``
-  method of OptionParser.  Generally only relevant if the ``version`` argument is
-  supplied to the OptionParser constructor.  As with :attr:`help` options, you
-  will rarely create ``version`` options, since :mod:`optparse` automatically adds
-  them when needed.
-
+* ``"version"``
 
-.. _optparse-option-attributes:
-
-Option attributes
-^^^^^^^^^^^^^^^^^
-
-The following option attributes may be passed as keyword arguments to
-``parser.add_option()``.  If you pass an option attribute that is not relevant
-to a particular option, or fail to pass a required option attribute,
-:mod:`optparse` raises :exc:`OptionError`.
-
-* :attr:`action` (default: ``"store"``)
-
-  Determines :mod:`optparse`'s behaviour when this option is seen on the command
-  line; the available options are documented above.
-
-* :attr:`!type` (default: ``"string"``)
-
-  The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the
-  available option types are documented below.
-
-* :attr:`dest` (default: derived from option strings)
-
-  If the option's action implies writing or modifying a value somewhere, this
-  tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the
-  ``options`` object that :mod:`optparse` builds as it parses the command line.
-
-* ``default``
-
-  The value to use for this option's destination if the option is not seen on the
-  command line.  See also ``parser.set_defaults()``.
-
-* ``nargs`` (default: 1)
-
-  How many arguments of type :attr:`!type` should be consumed when this option is
-  seen.  If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`.
-
-* ``const``
-
-  For actions that store a constant value, the constant value to store.
-
-* ``choices``
-
-  For options of type ``"choice"``, the list of strings the user may choose from.
-
-* ``callback``
-
-  For options with action ``"callback"``, the callable to call when this option
-  is seen.  See section :ref:`optparse-option-callbacks` for detail on the
-  arguments passed to ``callable``.
-
-* ``callback_args``, ``callback_kwargs``
-
-  Additional positional and keyword arguments to pass to ``callback`` after the
-  four standard callback arguments.
-
-* :attr:`help`
-
-  Help text to print for this option when listing all available options after the
-  user supplies a :attr:`help` option (such as ``"--help"``). If no help text is
-  supplied, the option will be listed without help text.  To hide this option, use
-  the special value ``SUPPRESS_HELP``.
-
-* ``metavar`` (default: derived from option strings)
-
-  Stand-in for the option argument(s) to use when printing help text. See section
-  :ref:`optparse-tutorial` for an example.
+  Prints the version number supplied to the OptionParser to stdout and exits.
+  The version number is actually formatted and printed by the
+  ``print_version()`` method of OptionParser.  Generally only relevant if the
+  ``version`` argument is supplied to the OptionParser constructor.  As with
+  :attr:`~Option.help` options, you will rarely create ``version`` options,
+  since :mod:`optparse` automatically adds them when needed.
 
 
 .. _optparse-standard-option-types:
@@ -1122,14 +1155,14 @@ to a particular option, or fail to pass a required option attribute,
 Standard option types
 ^^^^^^^^^^^^^^^^^^^^^
 
-:mod:`optparse` has five built-in option types: ``string``, ``int``,
-``choice``, ``float`` and ``complex``.  If you need to add new option types, see
-section :ref:`optparse-extending-optparse`.
+:mod:`optparse` has five built-in option types: ``"string"``, ``"int"``,
+``"choice"``, ``"float"`` and ``"complex"``.  If you need to add new
+option types, see section :ref:`optparse-extending-optparse`.
 
 Arguments to string options are not checked or converted in any way: the text on
 the command line is stored in the destination (or passed to the callback) as-is.
 
-Integer arguments (type ``int``) are parsed as follows:
+Integer arguments (type ``"int"``) are parsed as follows:
 
 * if the number starts with ``0x``, it is parsed as a hexadecimal number
 
@@ -1140,17 +1173,18 @@ Integer arguments (type ``int``) are parsed as follows:
 * otherwise, the number is parsed as a decimal number
 
 
-The conversion is done by calling ``int()`` with the appropriate base (2, 8, 10,
-or 16).  If this fails, so will :mod:`optparse`, although with a more useful
+The conversion is done by calling :func:`int` with the appropriate base (2, 8,
+10, or 16).  If this fails, so will :mod:`optparse`, although with a more useful
 error message.
 
-``float`` and ``complex`` option arguments are converted directly with
-``float()`` and ``complex()``, with similar error-handling.
+``"float"`` and ``"complex"`` option arguments are converted directly with
+:func:`float` and :func:`complex`, with similar error-handling.
 
-``choice`` options are a subtype of ``string`` options.  The ``choices`` option
-attribute (a sequence of strings) defines the set of allowed option arguments.
-``optparse.check_choice()`` compares user-supplied option arguments against this
-master list and raises :exc:`OptionValueError` if an invalid string is given.
+``"choice"`` options are a subtype of ``"string"`` options.  The
+:attr:`~Option.choices`` option attribute (a sequence of strings) defines the
+set of allowed option arguments.  :func:`optparse.check_choice` compares
+user-supplied option arguments against this master list and raises
+:exc:`OptionValueError` if an invalid string is given.
 
 
 .. _optparse-parsing-arguments:
@@ -1182,7 +1216,7 @@ and the return values are
    the leftover positional arguments after all options have been processed
 
 The most common usage is to supply neither keyword argument.  If you supply
-``values``, it will be modified with repeated ``setattr()`` calls (roughly one
+``values``, it will be modified with repeated :func:`setattr` calls (roughly one
 for every option argument stored to an option destination) and returned by
 :meth:`parse_args`.
 
@@ -1197,37 +1231,51 @@ traditional Unix exit status for command-line errors).
 Querying and manipulating your option parser
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The default behavior of the option parser can be customized slightly,
-and you can also poke around your option parser and see what's there.
-OptionParser provides several methods to help you out:
-
-``disable_interspersed_args()``
-  Set parsing to stop on the first non-option. Use this if you have a
-  command processor which runs another command which has options of
-  its own and you want to make sure these options don't get
-  confused. For example, each command might have a different
-  set of options.
-
-``enable_interspersed_args()``
-  Set parsing to not stop on the first non-option, allowing
-  interspersing switches with command arguments.  For example,
-  ``"-s arg1 --long arg2"`` would return ``["arg1", "arg2"]``
-  as the command arguments and ``-s, --long`` as options.
-  This is the default behavior.
-
-``get_option(opt_str)``
-   Returns the Option instance with the option string ``opt_str``, or ``None`` if
+The default behavior of the option parser can be customized slightly, and you
+can also poke around your option parser and see what's there.  OptionParser
+provides several methods to help you out:
+
+.. method:: OptionParser.disable_interspersed_args()
+
+   Set parsing to stop on the first non-option.  For example, if ``"-a"`` and
+   ``"-b"`` are both simple options that take no arguments, :mod:`optparse`
+   normally accepts this syntax::
+
+      prog -a arg1 -b arg2
+
+   and treats it as equivalent to  ::
+
+      prog -a -b arg1 arg2
+
+   To disable this feature, call :meth:`disable_interspersed_args`.  This
+   restores traditional Unix syntax, where option parsing stops with the first
+   non-option argument.
+
+   Use this if you have a command processor which runs another command which has
+   options of its own and you want to make sure these options don't get
+   confused.  For example, each command might have a different set of options.
+
+.. method:: OptionParser.enable_interspersed_args()
+
+   Set parsing to not stop on the first non-option, allowing interspersing
+   switches with command arguments.  This is the default behavior.
+
+.. method:: OptionParser.get_option(opt_str)
+
+   Returns the Option instance with the option string *opt_str*, or ``None`` if
    no options have that option string.
 
-``has_option(opt_str)``
-   Return true if the OptionParser has an option with option string ``opt_str``
+.. method:: OptionParser.has_option(opt_str)
+
+   Return true if the OptionParser has an option with option string *opt_str*
    (e.g., ``"-q"`` or ``"--verbose"``).
 
-``remove_option(opt_str)``
-   If the :class:`OptionParser` has an option corresponding to ``opt_str``, that option is
-   removed.  If that option provided any other option strings, all of those option
-   strings become invalid. If ``opt_str`` does not occur in any option belonging to
-   this :class:`OptionParser`, raises :exc:`ValueError`.
+.. method:: OptionParser.remove_option(opt_str)
+
+   If the :class:`OptionParser` has an option corresponding to *opt_str*, that
+   option is removed.  If that option provided any other option strings, all of
+   those option strings become invalid. If *opt_str* does not occur in any
+   option belonging to this :class:`OptionParser`, raises :exc:`ValueError`.
 
 
 .. _optparse-conflicts-between-options:
@@ -1257,10 +1305,11 @@ or with a separate call::
 
 The available conflict handlers are:
 
-   ``error`` (default)
-      assume option conflicts are a programming error and raise :exc:`OptionConflictError`
+   ``"error"`` (default)
+      assume option conflicts are a programming error and raise
+      :exc:`OptionConflictError`
 
-   ``resolve``
+   ``"resolve"``
       resolve option conflicts intelligently (see below)
 
 
@@ -1306,9 +1355,10 @@ Cleanup
 
 OptionParser instances have several cyclic references.  This should not be a
 problem for Python's garbage collector, but you may wish to break the cyclic
-references explicitly by calling ``destroy()`` on your OptionParser once you are
-done with it.  This is particularly useful in long-running applications where
-large object graphs are reachable from your OptionParser.
+references explicitly by calling :meth:`~OptionParser.destroy` on your
+OptionParser once you are done with it.  This is particularly useful in
+long-running applications where large object graphs are reachable from your
+OptionParser.
 
 
 .. _optparse-other-methods:
@@ -1318,51 +1368,34 @@ Other methods
 
 OptionParser supports several other public methods:
 
-* ``set_usage(usage)``
+.. method:: OptionParser.set_usage(usage)
 
-  Set the usage string according to the rules described above for the ``usage``
-  constructor keyword argument.  Passing ``None`` sets the default usage string;
-  use ``SUPPRESS_USAGE`` to suppress a usage message.
+   Set the usage string according to the rules described above for the ``usage``
+   constructor keyword argument.  Passing ``None`` sets the default usage
+   string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
 
-* ``enable_interspersed_args()``, ``disable_interspersed_args()``
+.. method:: OptionParser.set_defaults(dest=value, ...)
 
-  Enable/disable positional arguments interspersed with options, similar to GNU
-  getopt (enabled by default).  For example, if ``"-a"`` and ``"-b"`` are both
-  simple options that take no arguments, :mod:`optparse` normally accepts this
-  syntax::
+   Set default values for several option destinations at once.  Using
+   :meth:`set_defaults` is the preferred way to set default values for options,
+   since multiple options can share the same destination.  For example, if
+   several "mode" options all set the same destination, any one of them can set
+   the default, and the last one wins::
 
-     prog -a arg1 -b arg2
+      parser.add_option("--advanced", action="store_const",
+                        dest="mode", const="advanced",
+                        default="novice")    # overridden below
+      parser.add_option("--novice", action="store_const",
+                        dest="mode", const="novice",
+                        default="advanced")  # overrides above setting
 
-  and treats it as equivalent to  ::
+   To avoid this confusion, use :meth:`set_defaults`::
 
-     prog -a -b arg1 arg2
-
-  To disable this feature, call ``disable_interspersed_args()``.  This restores
-  traditional Unix syntax, where option parsing stops with the first non-option
-  argument.
-
-* ``set_defaults(dest=value, ...)``
-
-  Set default values for several option destinations at once.  Using
-  :meth:`set_defaults` is the preferred way to set default values for options,
-  since multiple options can share the same destination.  For example, if several
-  "mode" options all set the same destination, any one of them can set the
-  default, and the last one wins::
-
-     parser.add_option("--advanced", action="store_const",
-                       dest="mode", const="advanced",
-                       default="novice")    # overridden below
-     parser.add_option("--novice", action="store_const",
-                       dest="mode", const="novice",
-                       default="advanced")  # overrides above setting
-
-  To avoid this confusion, use :meth:`set_defaults`::
-
-     parser.set_defaults(mode="advanced")
-     parser.add_option("--advanced", action="store_const",
-                       dest="mode", const="advanced")
-     parser.add_option("--novice", action="store_const",
-                       dest="mode", const="novice")
+      parser.set_defaults(mode="advanced")
+      parser.add_option("--advanced", action="store_const",
+                        dest="mode", const="advanced")
+      parser.add_option("--novice", action="store_const",
+                        dest="mode", const="novice")
 
 
 .. _optparse-option-callbacks:
@@ -1377,7 +1410,7 @@ cases.  Quite often a simple callback is all you need.
 
 There are two steps to defining a callback option:
 
-* define the option itself using the ``callback`` action
+* define the option itself using the ``"callback"`` action
 
 * write the callback; this is a function (or method) that takes at least four
   arguments, as described below
@@ -1389,8 +1422,8 @@ Defining a callback option
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As always, the easiest way to define a callback option is by using the
-``parser.add_option()`` method.  Apart from :attr:`action`, the only option
-attribute you must specify is ``callback``, the function to call::
+:meth:`OptionParser.add_option` method.  Apart from :attr:`~Option.action`, the
+only option attribute you must specify is ``callback``, the function to call::
 
    parser.add_option("-c", action="callback", callback=my_callback)
 
@@ -1404,8 +1437,9 @@ number of command-line arguments.  This is where writing callbacks gets tricky;
 it's covered later in this section.
 
 :mod:`optparse` always passes four particular arguments to your callback, and it
-will only pass additional arguments if you specify them via ``callback_args``
-and ``callback_kwargs``.  Thus, the minimal callback function signature is::
+will only pass additional arguments if you specify them via
+:attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`.  Thus, the
+minimal callback function signature is::
 
    def my_callback(option, opt, value, parser):
 
@@ -1414,21 +1448,22 @@ The four arguments to a callback are described below.
 There are several other option attributes that you can supply when you define a
 callback option:
 
-:attr:`!type`
-   has its usual meaning: as with the ``store`` or ``append`` actions, it instructs
-   :mod:`optparse` to consume one argument and convert it to :attr:`!type`.  Rather
-   than storing the converted value(s) anywhere, though, :mod:`optparse` passes it
-   to your callback function.
+:attr:`~Option.type`
+   has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
+   instructs :mod:`optparse` to consume one argument and convert it to
+   :attr:`~Option.type`.  Rather than storing the converted value(s) anywhere,
+   though, :mod:`optparse` passes it to your callback function.
 
-``nargs``
+:attr:`~Option.nargs`
    also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
-   consume ``nargs`` arguments, each of which must be convertible to :attr:`!type`.
-   It then passes a tuple of converted values to your callback.
+   consume :attr:`~Option.nargs` arguments, each of which must be convertible to
+   :attr:`~Option.type`.  It then passes a tuple of converted values to your
+   callback.
 
-``callback_args``
+:attr:`~Option.callback_args`
    a tuple of extra positional arguments to pass to the callback
 
-``callback_kwargs``
+:attr:`~Option.callback_kwargs`
    a dictionary of extra keyword arguments to pass to the callback
 
 
@@ -1448,45 +1483,48 @@ where
 
 ``opt_str``
    is the option string seen on the command-line that's triggering the callback.
-   (If an abbreviated long option was used, ``opt_str`` will be the full, canonical
-   option string---e.g. if the user puts ``"--foo"`` on the command-line as an
-   abbreviation for ``"--foobar"``, then ``opt_str`` will be ``"--foobar"``.)
+   (If an abbreviated long option was used, ``opt_str`` will be the full,
+   canonical option string---e.g. if the user puts ``"--foo"`` on the
+   command-line as an abbreviation for ``"--foobar"``, then ``opt_str`` will be
+   ``"--foobar"``.)
 
 ``value``
    is the argument to this option seen on the command-line.  :mod:`optparse` will
-   only expect an argument if :attr:`!type` is set; the type of ``value`` will be
-   the type implied by the option's type.  If :attr:`!type` for this option is
-   ``None`` (no argument expected), then ``value`` will be ``None``.  If ``nargs``
+   only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
+   the type implied by the option's type.  If :attr:`~Option.type` for this option is
+   ``None`` (no argument expected), then ``value`` will be ``None``.  If :attr:`~Option.nargs`
    > 1, ``value`` will be a tuple of values of the appropriate type.
 
 ``parser``
-   is the OptionParser instance driving the whole thing, mainly useful because you
-   can access some other interesting data through its instance attributes:
+   is the OptionParser instance driving the whole thing, mainly useful because
+   you can access some other interesting data through its instance attributes:
 
    ``parser.largs``
-      the current list of leftover arguments, ie. arguments that have been consumed
-      but are neither options nor option arguments. Feel free to modify
-      ``parser.largs``, e.g. by adding more arguments to it.  (This list will become
-      ``args``, the second return value of :meth:`parse_args`.)
+      the current list of leftover arguments, ie. arguments that have been
+      consumed but are neither options nor option arguments. Feel free to modify
+      ``parser.largs``, e.g. by adding more arguments to it.  (This list will
+      become ``args``, the second return value of :meth:`parse_args`.)
 
    ``parser.rargs``
-      the current list of remaining arguments, ie. with ``opt_str`` and ``value`` (if
-      applicable) removed, and only the arguments following them still there.  Feel
-      free to modify ``parser.rargs``, e.g. by consuming more arguments.
+      the current list of remaining arguments, ie. with ``opt_str`` and
+      ``value`` (if applicable) removed, and only the arguments following them
+      still there.  Feel free to modify ``parser.rargs``, e.g. by consuming more
+      arguments.
 
    ``parser.values``
       the object where option values are by default stored (an instance of
-      optparse.OptionValues).  This lets callbacks use the same mechanism as the rest
-      of :mod:`optparse` for storing option values; you don't need to mess around with
-      globals or closures.  You can also access or modify the value(s) of any options
-      already encountered on the command-line.
+      optparse.OptionValues).  This lets callbacks use the same mechanism as the
+      rest of :mod:`optparse` for storing option values; you don't need to mess
+      around with globals or closures.  You can also access or modify the
+      value(s) of any options already encountered on the command-line.
 
 ``args``
-   is a tuple of arbitrary positional arguments supplied via the ``callback_args``
-   option attribute.
+   is a tuple of arbitrary positional arguments supplied via the
+   :attr:`~Option.callback_args` option attribute.
 
 ``kwargs``
-   is a dictionary of arbitrary keyword arguments supplied via ``callback_kwargs``.
+   is a dictionary of arbitrary keyword arguments supplied via
+   :attr:`~Option.callback_kwargs`.
 
 
 .. _optparse-raising-errors-in-callback:
@@ -1494,11 +1532,11 @@ where
 Raising errors in a callback
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The callback function should raise :exc:`OptionValueError` if there are any problems
-with the option or its argument(s).  :mod:`optparse` catches this and terminates
-the program, printing the error message you supply to stderr.  Your message
-should be clear, concise, accurate, and mention the option at fault.  Otherwise,
-the user will have a hard time figuring out what he did wrong.
+The callback function should raise :exc:`OptionValueError` if there are any
+problems with the option or its argument(s).  :mod:`optparse` catches this and
+terminates the program, printing the error message you supply to stderr.  Your
+message should be clear, concise, accurate, and mention the option at fault.
+Otherwise, the user will have a hard time figuring out what he did wrong.
 
 
 .. _optparse-callback-example-1:
@@ -1514,7 +1552,7 @@ records that the option was seen::
 
    parser.add_option("--foo", action="callback", callback=record_foo_seen)
 
-Of course, you could do that with the ``store_true`` action.
+Of course, you could do that with the ``"store_true"`` action.
 
 
 .. _optparse-callback-example-2:
@@ -1581,12 +1619,12 @@ Callback example 5: fixed arguments
 
 Things get slightly more interesting when you define callback options that take
 a fixed number of arguments.  Specifying that a callback option takes arguments
-is similar to defining a ``store`` or ``append`` option: if you define
-:attr:`!type`, then the option takes one argument that must be convertible to
-that type; if you further define ``nargs``, then the option takes ``nargs``
-arguments.
+is similar to defining a ``"store"`` or ``"append"`` option: if you define
+:attr:`~Option.type`, then the option takes one argument that must be
+convertible to that type; if you further define :attr:`~Option.nargs`, then the
+option takes :attr:`~Option.nargs` arguments.
 
-Here's an example that just emulates the standard ``store`` action::
+Here's an example that just emulates the standard ``"store"`` action::
 
    def store_value(option, opt_str, value, parser):
        setattr(parser.values, option.dest, value)
@@ -1673,32 +1711,36 @@ Adding new types
 ^^^^^^^^^^^^^^^^
 
 To add new types, you need to define your own subclass of :mod:`optparse`'s
-Option class.  This class has a couple of attributes that define
-:mod:`optparse`'s types: :attr:`TYPES` and :attr:`TYPE_CHECKER`.
+:class:`Option` class.  This class has a couple of attributes that define
+:mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
 
-:attr:`TYPES` is a tuple of type names; in your subclass, simply define a new
-tuple :attr:`TYPES` that builds on the standard one.
+.. attribute:: Option.TYPES
 
-:attr:`TYPE_CHECKER` is a dictionary mapping type names to type-checking
-functions.  A type-checking function has the following signature::
+   A tuple of type names; in your subclass, simply define a new tuple
+   :attr:`TYPES` that builds on the standard one.
 
-   def check_mytype(option, opt, value)
+.. attribute:: Option.TYPE_CHECKER
 
-where ``option`` is an :class:`Option` instance, ``opt`` is an option string
-(e.g., ``"-f"``), and ``value`` is the string from the command line that must be
-checked and converted to your desired type.  ``check_mytype()`` should return an
-object of the hypothetical type ``mytype``.  The value returned by a
-type-checking function will wind up in the OptionValues instance returned by
-:meth:`OptionParser.parse_args`, or be passed to a callback as the ``value``
-parameter.
+   A dictionary mapping type names to type-checking functions.  A type-checking
+   function has the following signature::
 
-Your type-checking function should raise :exc:`OptionValueError` if it encounters any
-problems.  :exc:`OptionValueError` takes a single string argument, which is passed
-as-is to :class:`OptionParser`'s :meth:`error` method, which in turn prepends the program
-name and the string ``"error:"`` and prints everything to stderr before
-terminating the process.
+      def check_mytype(option, opt, value)
 
-Here's a silly example that demonstrates adding a ``complex`` option type to
+   where ``option`` is an :class:`Option` instance, ``opt`` is an option string
+   (e.g., ``"-f"``), and ``value`` is the string from the command line that must
+   be checked and converted to your desired type.  ``check_mytype()`` should
+   return an object of the hypothetical type ``mytype``.  The value returned by
+   a type-checking function will wind up in the OptionValues instance returned
+   by :meth:`OptionParser.parse_args`, or be passed to a callback as the
+   ``value`` parameter.
+
+   Your type-checking function should raise :exc:`OptionValueError` if it
+   encounters any problems.  :exc:`OptionValueError` takes a single string
+   argument, which is passed as-is to :class:`OptionParser`'s :meth:`error`
+   method, which in turn prepends the program name and the string ``"error:"``
+   and prints everything to stderr before terminating the process.
+
+Here's a silly example that demonstrates adding a ``"complex"`` option type to
 parse Python-style complex numbers on the command line.  (This is even sillier
 than it used to be, because :mod:`optparse` 1.3 added built-in support for
 complex numbers, but never mind.)
@@ -1709,7 +1751,7 @@ First, the necessary imports::
    from optparse import Option, OptionValueError
 
 You need to define your type-checker first, since it's referred to later (in the
-:attr:`TYPE_CHECKER` class attribute of your Option subclass)::
+:attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::
 
    def check_complex(option, opt, value):
        try:
@@ -1726,9 +1768,9 @@ Finally, the Option subclass::
        TYPE_CHECKER["complex"] = check_complex
 
 (If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
-up modifying the :attr:`TYPE_CHECKER` attribute of :mod:`optparse`'s Option
-class. This being Python, nothing stops you from doing that except good manners
-and common sense.)
+up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
+Option class.  This being Python, nothing stops you from doing that except good
+manners and common sense.)
 
 That's it!  Now you can write a script that uses the new option type just like
 any other :mod:`optparse`\ -based script, except you have to instruct your
@@ -1755,45 +1797,50 @@ Adding new actions is a bit trickier, because you have to understand that
 
 "store" actions
    actions that result in :mod:`optparse` storing a value to an attribute of the
-   current OptionValues instance; these options require a :attr:`dest` attribute to
-   be supplied to the Option constructor
+   current OptionValues instance; these options require a :attr:`~Option.dest`
+   attribute to be supplied to the Option constructor.
 
 "typed" actions
-   actions that take a value from the command line and expect it to be of a certain
-   type; or rather, a string that can be converted to a certain type.  These
-   options require a :attr:`!type` attribute to the Option constructor.
+   actions that take a value from the command line and expect it to be of a
+   certain type; or rather, a string that can be converted to a certain type.
+   These options require a :attr:`~Option.type` attribute to the Option
+   constructor.
 
-These are overlapping sets: some default "store" actions are ``store``,
-``store_const``, ``append``, and ``count``, while the default "typed" actions
-are ``store``, ``append``, and ``callback``.
+These are overlapping sets: some default "store" actions are ``"store"``,
+``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
+actions are ``"store"``, ``"append"``, and ``"callback"``.
 
 When you add an action, you need to categorize it by listing it in at least one
 of the following class attributes of Option (all are lists of strings):
 
-:attr:`ACTIONS`
-   all actions must be listed in ACTIONS
+.. attribute:: Option.ACTIONS
+
+   All actions must be listed in ACTIONS.
+
+.. attribute:: Option.STORE_ACTIONS
+
+   "store" actions are additionally listed here.
+
+.. attribute:: Option.TYPED_ACTIONS
 
-:attr:`STORE_ACTIONS`
-   "store" actions are additionally listed here
+   "typed" actions are additionally listed here.
 
-:attr:`TYPED_ACTIONS`
-   "typed" actions are additionally listed here
+.. attribute:: Option.ALWAYS_TYPED_ACTIONS
 
-``ALWAYS_TYPED_ACTIONS``
-   actions that always take a type (i.e. whose options always take a value) are
+   Actions that always take a type (i.e. whose options always take a value) are
    additionally listed here.  The only effect of this is that :mod:`optparse`
-   assigns the default type, ``string``, to options with no explicit type whose
-   action is listed in ``ALWAYS_TYPED_ACTIONS``.
+   assigns the default type, ``"string"``, to options with no explicit type
+   whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
 
 In order to actually implement your new action, you must override Option's
 :meth:`take_action` method and add a case that recognizes your action.
 
-For example, let's add an ``extend`` action.  This is similar to the standard
-``append`` action, but instead of taking a single value from the command-line
-and appending it to an existing list, ``extend`` will take multiple values in a
-single comma-delimited string, and extend an existing list with them.  That is,
-if ``"--names"`` is an ``extend`` option of type ``string``, the command line
-::
+For example, let's add an ``"extend"`` action.  This is similar to the standard
+``"append"`` action, but instead of taking a single value from the command-line
+and appending it to an existing list, ``"extend"`` will take multiple values in
+a single comma-delimited string, and extend an existing list with them.  That
+is, if ``"--names"`` is an ``"extend"`` option of type ``"string"``, the command
+line ::
 
    --names=foo,bar --names blah --names ding,dong
 
@@ -1820,29 +1867,30 @@ Again we define a subclass of Option::
 
 Features of note:
 
-* ``extend`` both expects a value on the command-line and stores that value
-  somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS`
+* ``"extend"`` both expects a value on the command-line and stores that value
+  somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
+  :attr:`~Option.TYPED_ACTIONS`.
 
-* to ensure that :mod:`optparse` assigns the default type of ``string`` to
-  ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as
-  well
+* to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
+  ``"extend"`` actions, we put the ``"extend"`` action in
+  :attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
 
 * :meth:`MyOption.take_action` implements just this one new action, and passes
   control back to :meth:`Option.take_action` for the standard :mod:`optparse`
-  actions
+  actions.
 
-* ``values`` is an instance of the optparse_parser.Values class, which
-  provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
-  essentially :func:`getattr` with a safety valve; it is called as  ::
+* ``values`` is an instance of the optparse_parser.Values class, which provides
+  the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
+  essentially :func:`getattr` with a safety valve; it is called as ::
 
      values.ensure_value(attr, value)
 
   If the ``attr`` attribute of ``values`` doesn't exist or is None, then
-  ensure_value() first sets it to ``value``, and then returns 'value. This is very
-  handy for actions like ``extend``, ``append``, and ``count``, all of which
-  accumulate data in a variable and expect that variable to be of a certain type
-  (a list for the first two, an integer for the latter).  Using
+  ensure_value() first sets it to ``value``, and then returns 'value. This is
+  very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all
+  of which accumulate data in a variable and expect that variable to be of a
+  certain type (a list for the first two, an integer for the latter).  Using
   :meth:`ensure_value` means that scripts using your action don't have to worry
-  about setting a default value for the option destinations in question; they can
-  just leave the default as None and :meth:`ensure_value` will take care of
+  about setting a default value for the option destinations in question; they
+  can just leave the default as None and :meth:`ensure_value` will take care of
   getting it right when it's needed.