[Doc-SIG] Python docs in reST?

Torsten Bronger bronger at physik.rwth-aachen.de
Wed May 18 19:41:43 CEST 2005


Michael Hudson <mwh at python.net> writes:

> [...]
> I believe there has been a long-ish term standing offer from
> assorted people to turn plain text docs into suitable latex for
> the docs (if not, let me make one).
> The main reason that Python's documentation is patchy in places is
> because writing good content is hard!  Dealing with *any* format
> is minor in comparison.

The willingness to contribute good content is an important premise,
no doubt.  However, it is also important that the community has
agreed on one format.  I'm not prepared to write in (or worse,
convert to) a certain format that's abandonned later.

I came to Python three months ago, and it's still not clear to me
which format one should use for the documentation (which is very
important to me and, in contrast to most developers, I enjoy to

LaTeX seems to be a we-want-to-get-rid-of-it, and reST is still not
really ready.  (I used the latter, nevertheless.  My main reason was
that LaTeX cannot be autoconverted reliably.)

So all in all, I do think that Python would benefit from a clear
homogeneous documentation policy, combined with strong reST tools.


Torsten Bronger, aquisgrana, europa vetus

More information about the Doc-SIG mailing list