[Doc-SIG] Python docs in reST
janssen at parc.xerox.com
Fri May 27 06:55:10 CEST 2005
Martin Blais writes:
> i see a contradiction: docutils is a toolchain with a parser that
> extracts semantic (paragraphs, sections, etc.) from source documents
> that have no markup (or very little). it has been explicitly
> discussed NOT to add too much visible markup on the docutils list, and
> AFAIK it is an explicit goal of rest to keep the input syntax as
> unobstrusive as possible.
> and then, having too little markup does not allow us to do all the
> things that we need to do for a proper documentation system.
This is the contradiction I was trying to point out last week. After
using reST to document a system, I think I'd pick something else next
time. I like the general "markup on a different line" style of troff
right now. Though it would need a new macro package to really use, so
LaTeX is probably just as good, given the right macro package.
More information about the Doc-SIG