[Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code

[Michael Hudson]

Michael Foord <mike at pcblokes.com> writes:

> A brief but resounding +1 to the idea of standardising Python doc
> generation using docutils.

Are you talking about the existing Python documentation?  Or just a
way of making the "blue arrows" HTML from ReST?

The issue with the existing documentation is that it exists, and in
latex...

> The python documentation is very nicely presented and *ought* to be
> the standard style for people documenting third party modules. The
> toolset to produce the documentation currently seems a bit arcane. I
> may just be a luddite - but every time I've looked into it I've ended
> up with a headache (although I've not put any degree of real effort
> into it !).

On Unix with a working Latex installation, it's really easy (these
days, now Latex2HTML is less of a pig to install).

> Being able to write docs in reST and use docutils to produce them
> sounds great. The *main* drawback will be that docutils doesn't yet
> support multipage documents.

ISTR talk of a writer that wrote latex in the style of the existing
Python documentation, which would get around that problem (but not the
toolchain ones).

Cheers,
mwh

-- 
  <glyph> "Fetch me my internet pants."
                                                -- from Twisted.Quotes