[Doc-SIG] Python docs in reST?
Felix Wiemann
Felix.Wiemann at gmx.net
Fri May 27 15:48:42 CEST 2005
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/
More information about the Doc-SIG
mailing list