[Doc-SIG] Python docs in reST?

[Felix Wiemann]

Torsten Bronger wrote:

> [Field lists:] I dislike this table-like style.  Currently, my source
> may contain this:
>
> unlock
> ......
>
> Relinquish a lock for the specified resource.
>
> :Call: unlock(vi)
> :Parameters:
>     `vi` : ViSession
>         Unique logical identifier to a session.
> :Return values:
>     None.
>
> I want "Call" and "Parameters" to go away, and I don't want to feel
> forced to start a new section for every function.

These two problems can be solved with roles and definition lists:

    .. role:: call

    unlock
        Relinquish a lock for the specified resource.

        :call:`unlock(vi)`
            `vi` : ViSession
                Unique logical identifier to a session.
        Return values:
            None.

If you like, you can add a "parameter" role and write ::

    :parameter:`vi` : ViSession

but that looks rather clumsy, because you'd have to mark up every single
parameter.

If you don't like the deep nesting and the duplication of the function
name, you could place the :call: definition at the top level:

    .. role:: call
    .. role:: parameter

    :call:`unlock(vi)`
        Relinquish a lock for the specified resource.

        :parameter:`vi` : ViSession
            Unique logical identifier to a session.
        Return values:
            None.

Looks quite nice in the HTML output, IMO.

> But first and foremost, I want to have the impression that I tell the
> reST interpreter everything I can.  Here, for example, I know that
> "unlock" is the function's name, "vi" is a parameter object,
> "ViSession" is a type.  However, I can't pass this knowledge to reST.

You can.  Just define a role for every thing you want to mark up, like:

    .. role:: function_name
    .. role:: type
    
    etc.

And then write e.g. :type:`ViSession`.  This looks over-formalized (for
my taste), but that's not really reST's fault -- you have that problem
in every markup language, I'd suppose.

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

http://www.ososo.de/