[Doc-SIG] Python docs in reST?

[Michael Hudson]

Skip Montanaro <skip at pobox.com> writes:

>     >> * dump latex2html
>
>     Michael> It works most of the time these days!
>
> I was under the impression that Fred was still dealing with a forked version
> of the code and that it was still fairly fragile.

No, we use stock latex2html.  There a bunch of style files and
customizations on top that probably count as a little fragile but they
certainly work for me.

>     >> * better potential HTML generation options (like HTML w/ an integrated
>     >> annotation capability)
>
>     Michael> But only, very much "potential".
>
> Sure, but how much experimentation do you think is practical using
> latex2html?

Not a lot, I'll grant you.  More if you're called "Fred" :)

>     >> * possibly enlarge pool of documentation contributors
>
>     Michael> Yeah, right.  This is where my lack of faith in humanity comes
>     Michael> out.
>
> Understood.
>
>     Michael> I believe there has been a long-ish term standing offer from
>     Michael> assorted people to turn plain text docs into suitable latex for
>     Michael> the docs (if not, let me make one).
>
> A number of people (myself included) have made this offer on multiple
> occsions, generally in response to some variant of "Python's documentation
> sucks".  (Which we all know it doesn't, but they complain just the same.)

Yup.

>     Michael> The main reason that Python's documentation is patchy in places
>     Michael> is because writing good content is hard!  Dealing with *any*
>     Michael> format is minor in comparison.
>
> I would be happy if people contributed examples or submitted enhancement
> requests that referred to cookbook recipes.

Me too.

Cheers,
mwh

-- 
  I'm okay with intellegent buildings, I'm okay with non-sentient
  buildings. I have serious reservations about stupid buildings.
     -- Dan Sheppard, ucam.chat (from Owen Dunn's summary of the year)