[Doc-SIG] Python docs in reST?

[Michael Hudson]

Torsten Bronger <bronger at physik.rwth-aachen.de> writes:

> Hallöchen!
>
> 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
> create).

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!

Cheers,
mwh

-- 
  Ability to type on a computer terminal is no guarantee of sanity,
  intelligence, or common sense. 
                                 -- Gene Spafford's Axiom #2 of Usenet