[Doc-SIG] Python Extensions to the reStructuredText Markup Specification

[David Goodger]

================================================================
 Python Extensions to the reStructuredText Markup Specification
================================================================
Author: David Goodger
Contact: dgoodger@bigfoot.com
Version: 0.2
Date: 2001-05-29

This document details Python-specific additions to and interpretations of
the base `reStructuredText Markup Specification`_, part of the
reStructuredText_ project, in the context of the `Python Docstring
Processing System`_.

----------------
 Syntax Details
----------------

For definitive element hierarchy details, see the "Python Plaintext
Document Interface DTD" XML document type definition, ppdi.dtd_ (which
modifies the generic gpdi.dtd_). Descriptions below list 'DTD elements'
(XML 'generic identifiers') corresponding to syntax constructs.

Option Lists
============
DTD elements: option_list, option_list_item, option, short_option,
long_option, option_argument, description.

Option lists are two-column lists of command-line options and descriptions.
There are two types of options: short and long. Short options consist of
one dash and an option letter. Long options consist of two dashes and an
option word. Both short and long options may be followed by a single space
and an argument placeholder. An option list item may have multiple
command-line options listed, separated by comma-space. There must be at
least two spaces between the option(s) and the description. The description
may contain multiple body elements. As with other types of lists, blank
lines are required before the first option list item and after the last,
but are optional between option entries. For example::

    -a         Output all
    -b         Output both (this description is
               quite long)
    -c arg     Output just arg.
    --long     Output all day long.
    -2, --two  This option has two variants.

    -p         This option has two paragraphs in the description.
               This is the first.

               This is the second.

Doctest Blocks
==============
DTD element: doctest_block.

Doctest blocks are interactive Python sessions cut-and-pasted into
docstrings. They are meant to illustrate usage by example, and provide an
elegant and powerful testing environment via the doctest module in the
Python standard library.

Doctest blocks are text blocks which begin with '>>> ', the Python
interactive interpreter main prompt, and end with a blank line. Doctest
blocks are treated as a special case of literal blocks, without requiring
the literal block syntax. If both are present, the literal block syntax
takes priority over Doctest block syntax::

    This is an ordinary paragraph.

    >>> print 'this is a Doctest block'
    this is a Doctest block

    The following is a literal block::

        >>> This is not recognized as a doctest block by reStructuredText.
        It *will* be recognized by the doctest module, though!

Indentation is not required for doctest blocks.

Interpreted Text
================
DTD elements: package, module, class, method, function, module_attribute,
class_attribute, instance_attribute, variable, parameter, type,
exception_class, warning_class.

In Python docstrings, interpreted text is used to classify and mark up
program identifiers, such as the names of variables, functions, classes,
and modules. If the identifier alone is given, its role is inferred
implicitly according to the Python namespace lookup rules. For functions
and methods (even when dynamically assigned), parentheses ('()') may be
included::

    This function uses `another()` to do its work.

For class, instance and module attributes, dotted identifiers are used when
necessary::

    class Keeper(Storer):

        """
        Extend `Storer`. Class attribute `instances` keeps track of the
        number of `Keeper` objects instantiated.
        """

        instances = 0
        """How many `Keeper` objects are there?"""

        def __init__(self):
            """
            Extend `Storer.__init__()` to keep track of instances.

            Keep count in `self.instances` and data in `self.data`.
            """
            Storer.__init__(self)
            self.instances += 1

            self.data = []
            """Store data in a list, most recent last."""

        def storedata(self, data):
            """
            Extend `Storer.storedata()`; append new `data` to a list (in
            `self.data`).
            """
            self.data = data

To classify identifiers explicitly, the role is given along with the
identifier in either prefix or suffix form::

    Use `method: Keeper.storedata` to store the object's data in the
    `Keeper.data :instance attribute`.

The role may be one of 'package', 'module', 'class', 'method', 'function',
'module attribute', 'moduleatt', 'class attribute', 'classatt', 'instance
attribute', 'instanceatt', 'variable', 'parameter', 'type', 'exception',
or 'warning'. Other roles may be defined.

.. _reStructuredText Markup Specification:
   http://structuredtext.sf.net/spec/reStructuredText.txt
.. _reStructuredText: http://structuredtext.sf.net
.. _Python Docstring Processing System: http://docstring.sf.net
.. _ppdi.dtd: http://docstring.sf.net/spec/ppdi.dtd
.. _gpdi.dtd: http://docstring.sf.net/spec/gpdi.dtd