[Doc-SIG] Python docs in reST?

[Felix Wiemann]

Torsten Bronger wrote:

> Felix Wiemann <Felix.Wiemann at gmx.net> writes:
>
>> 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.

It doesn't need to, because it wouldn't treat them differently.

However, since the markup is there, any tool can recognize those special
tokens.  You can apply different formatting in the HTML output using a
CSS stylesheet, and you can extract them from Docutils' XML output just
using an XML parser.

> Such basic concepts should be in reST's core in my opinion.

I don't think that's a good idea.  It's too much explicit markup, and I
just don't see the practical use of this.  And after all, integrating it
into reST's core would just mean making the ".. role:: function_name"
commands implicit; there's no reason you cannot assemble them in a file
and explicitly ".. include::" them yourself.

>> And then write e.g. :type:`ViSession`.  This looks over-formalized
>
> If you define a template for a method or function explanation, it
> looks rwther simple in the source.

Yeah, that's true.  It's certainly something worth keeping in mind when
writing a Python documentation system with Docutils.

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

http://www.ososo.de/