[Python-Dev] reST limitations? (was Re: status of development documentation)

[Fredrik Lundh]

Martin Blais wrote:

> > So, definitions of functions, classes, and other structured stuff would
> > just use fields under a directive, and references to those definitions
> > would just be reST links.
>
> So you end up with a document with a bunch of custom directives, like::
>
> .. python-class::  MyClass
>    :arg: comfobulator
>    :arg optional: bliptor
>
>    My Class description.
>
> This does not look significantly better to me than the LaTeX code, and
> the docutils directives are not as flexible as the commands provided
> by tex/latex.

Except that tex/latex don't give you the same structure.  Using the real-
life example from the documentation list again:

- LaTeX with Python extensions:

   \begin{funcdesc}{dumps}{params\optional{, methodname\optional{,
                            methodresponse\optional{, encoding}}}}
    Convert \var{params} into an XML-RPC request.
    or into a response if \var{methodresponse} is true.
    \var{params} can be either a tuple of arguments or an instance of the
    \exception{Fault} exception class.  If \var{methodresponse} is true,
    only a single value can be returned, meaning that \var{params} must be of length 1.
    \var{encoding}, if supplied, is the encoding to use in the generated
    XML; the default is UTF-8.
    \end{funcdesc}

- hypothetical ReST (based on martin's example and the above LaTeX
  markup):

    .. python-function:: dumps
    :arg: params
    :arg optional: methodname
    :arg optional: methodresponse
    :arg optional: encoding

    Convert _`params` into an XML-RPC request, or into a response if
    _`methodresponse` is true.
    _`params` can be either a tuple of arguments or an instance of the
    `:exception: _`Fault` exception class.  If _`methodresponse` is true,
    only a single value can be returned, meaning that _`params` must be
    of length 1.
    _`encoding`, if supplied, is the encoding to use in the generated
    XML; the default is UTF-8.
    .. python-function-end

Informationwise, this is mostly identical to the latex example, except that
you can use existing tools to get an XML structure from this markup.

- JavaDoc/PythonDoc markup:

    Converts a Python tuple or a Fault instance to an XML-RPC request.

    @def dumps(params, **options)
    @param params A tuple or {@link Fault} instance.
    @keyparam methodname If given, create a call request for
        this method name.
    @keyparam methodresponse If given, create a response request.
        If used with a tuple, the tuple must be a singleton (that is,
        it must contain exactly one element).
    @keyparam encoding The encoding to use for this request. Defaults to
        UTF-8.
    @return A string containing marshalled data.

The LaTeX solution is one line shorter, but the JavaDoc/PythonDoc solution
squeezes a lot more structural information into those 11 lines.

Also note that the JavaDoc/PythonDoc version is the only one that reflects
the designer's intent: all arguments but the first are keyword options, not
optional positional arguments (I don't know how to express that efficiently
in today's LaTeX markup).

It's also the only one here where existing tools can be used to get a clean
information model

   <function name="xmlrpclib.dumps">
        <info>
            <name>dumps</name>
            <summary>Convert a Python tuple or a Fault instance to an
                XML-RPC request.</summary>
            <description>Convert a Python tuple or a Fault instance to an
                XML-RPC request.</description>
            <def>dumps(params, **options)</def>
            <param name="params">A tuple or Fault instance.</param>
            <keyparam name="methodname">If given, create a methodCall
                request for this method name.</keyparam>
            <keyparam name="methodresponse">If given, create a
                methodResponse request. If used with a tuple, the tuple must
                be a singleton (that is, it must contain exactly one element).
                </keyparam>
            <keyparam name="encoding">The request encoding. Defaults to
                UTF-8.</keyparam>
            <return>A string containing marshalled data.</return>
        </info>
    </function>

for further processing (using XSLT to turn this into nice HTML is trivial, for
example).  It's impossible to extract this level of information from the given
LaTeX and ReST examples.

</F>