[Doc-SIG] Python docs in reST

[Bill Janssen]

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.

Bill