[Doc-SIG] Python docs in reST?

[Michael Hudson]

Skip Montanaro <skip at pobox.com> writes:

> A thread on c.l.py ("Python Documentation (should be better?)") got me to
> thinking about options for improving/restructuring the online documentation.
> That led me to thinking about converting the current docs to reST.  A scan
> of the last year's worth of list archives didn't yield any obvious
> discussion on the topic, but I find it hard to believe the topic hasn't been
> discussed in the past.  Pointers to past threads cheerfully accepted.

I thought it had too, but maybe only on python-list.

I'm not so sure it would make much difference, but maybe that's just
my cynicism.

> It seems to me that converting to reST has a couple obvious benefits:
>
>     * dump latex2html

It works most of the time these days!

>     * better potential HTML generation options (like HTML w/ an integrated
>       annotation capability)

But only, very much "potential".

>     * possibly enlarge pool of documentation contributors

Yeah, right.  This is where my lack of faith in humanity comes out.

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.

> Fred wrote some Latex->ESIS->SGML tools that look like they might possibly
> be redirected to the more-or-less one-time task of converting to reST.

I don't know if the task of generating reST has been really solved,
either.

Cheers,
mwh

-- 
  > I wouldn't want to live without readline, but some of the 
  > things it does call for the application of thumbscrews.
                                                   -- me on python-dev