[Doc-SIG] Python docs in reST?
mwh at python.net
Thu May 19 10:08:31 CEST 2005
Torsten Bronger <bronger at physik.rwth-aachen.de> writes:
> 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.
Well, there are two questions here, which possibly -- but don't --
have the same answer: "what format is the documentation for Python
in?" and "what format should I use for documenting my Python module?"
The answer to the first has been "Latex" for about 10 years (and was
"framemaker" before that, I think). The second doesn't really have a
canonical answer, and I get the feeling that this is what bothers
people. Reasonable answers are "Latex", like CPython, or "ReST".
> 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
Here you're talking about the second question, right?
> 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.)
I'm not sure what you mean for the latter.
> So all in all, I do think that Python would benefit from a clear
> homogeneous documentation policy, combined with strong reST tools.
I'm not going to argue with that!
Ability to type on a computer terminal is no guarantee of sanity,
intelligence, or common sense.
-- Gene Spafford's Axiom #2 of Usenet
More information about the Doc-SIG