[Doc-SIG] Python docs in reST?

[Torsten Bronger]

Hallöchen!

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

> Torsten Bronger wrote:
>
>> [...]
>>
>> :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:
>
> [...]
>
> Looks quite nice in the HTML output, IMO.

Yes indeed.

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

This is only half the way, because the parser doesn't know what it
really means.  Such basic concepts should be in reST's core in my
opinion.

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

It depends on how implicit you dare to make reST.  If you define a
template for a method or function explanation, it looks rwther
simple in the source.  Nevertheless, the transformer knows exactly
what every token means.  (As long as the parser can rightfully
assume that you describe *Python* code.)

Tschö,
Torsten.

-- 
Torsten Bronger, aquisgrana, europa vetus