[Python-Dev] The docs, reloaded

[Martin Blais]

On 5/22/07, Nick Coghlan <ncoghlan at gmail.com> wrote:
>
> So in Armin's example, I found the reST version *much* easier to read.
> Whether that difference in perception is due simply to my relative lack
> of experience in using LaTeX, or to something else, I have no idea.

- If you make a mistake in LaTeX, you will get a cryptic error which
is usually a little difficult to figure out (if you're not used to
it).  You can an error though.

- If you make a mistake in ReST, you will often get no warning nor
error, and not the desired output.  If you were to use the amount of
markup in that example, you would have to check your text with rst2xml
frequently to make sure it groks what you're trying to say.  (And I've
been there: I wrote an entire project who relies specifically on this,
on precise structures generated by docutils (http://furius.ca/nabu/).
It's *very* easy to make subtle errors that generate something else
than what you want.)

ReST works well only when there is little markup.  Writing code
documentation generally requires a lot of markup, you want to make
variables, classes, functions, parameters, constants, etc..  (A better
avenue IMHO would be to augment docutils with some code to
automatically figure out the syntax of functions, parameters, classes,
etc., i.e., less markup, and if we do this in Python we may be able to
use introspection.  This is a challenge, however, I don't know if it
can be done at all.)