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

Fredrik Lundh fredrik at pythonware.com
Fri Dec 23 09:14:26 CET 2005

• Previous message: [Python-Dev] reST limitations? (was Re: status of development documentation)
• Next message: [Python-Dev] status of development documentation
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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

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.

• Previous message: [Python-Dev] reST limitations? (was Re: status of development documentation)
• Next message: [Python-Dev] status of development documentation
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

More information about the Python-Dev mailing list