[Doc-SIG] Python docs in reST
Fred L. Drake, Jr.
fdrake at acm.org
Fri May 27 20:37:40 CEST 2005
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
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 L. Drake, Jr. <fdrake at acm.org>
More information about the Doc-SIG