[Doc-SIG] Python docs in reST

[Fred L. Drake, Jr.]

On Friday 27 May 2005 13:03, Felix Wiemann wrote:
 > First of all, just to avoid misunderstandings, I don't think roles like
 > :function: or :class: will be added to standard-reST.  If it all, it
 > will be an extension (possibly shipped with the Docutils distribution
 > though) which must be explicitly activated (probably from inside the
 > reST document, like ".. extension:: python-doc").

I'd rather such an extension not be part of the docutils package; it should be 
possible to keep a separate release schedule for the extension package.

 > While the goal of reST is to avoid explicit markup, IMO it's fine to use
 > explicit markup where considered necessary and it doesn't make reST less
 > useful.

Yep.  I just don't see a way to avoid lots of markup.  There are probably some 
ways to make the default interpreted text role context-sensitive to avoid 
having to be really heavy with markup in places where we can determine what's 
the most reasonable role.  (`var` in a function description with an argument 
named "var" should be able to determine that `var` refers to the parameter.)

 > And even if you mark up function names, parameters and class names,
 > still a lot of reST's WYSIWYG and simplicity is retained, and that's a
 > big advantage over LaTeX.

The ReST syntax is certainly nicer for things like different kinds of lists.  
Being able to specialize lists is a requirement, but should not be too 
difficult using specialized directives.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>