[Doc-SIG] Python docs in reST?

[Torsten Bronger]

Hallöchen!

Felix Wiemann <Felix.Wiemann at gmx.net> writes:

> Torsten Bronger wrote:
>
>> I use field lists at the moment.  That's okay, but it's not real
>> logical markup since the reST interpreter has no chance to
>> recognise it as a function definition.  Besides, its pdf and HTML
>> results are poor.
>
> The PDF output is being worked on.  What's bothering you about the
> HTML output?

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.  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.

http://pp3.sf.net/manual/Other-layout-parameters.html shows how it
could look like:  Just a signature line with proper emphasis on the
functions's name and all identifiers in italics.  Big skip before
it, and indentation of the whole explanation.

Tschö,
Torsten.

-- 
Torsten Bronger, aquisgrana, europa vetus