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

[Michael Foord]

Michael Hudson wrote:

>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?
>
>  
>
 From my POV - just blue arrows HTML from reST would be hunky dory. I 
guess it might already be possible with judicious use of header, footer, 
and CSS. Perhaps I should investigate - more docutils directives to 
support documentation of python support would be a a definite plus as 
well though.

>The issue with the existing documentation is that it exists, and in
>latex...
>
>  
>
Right - is Python documentation really written straight into LaTex markup ?

>>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).
>
>  
>

Hmm.. I haven't heard any talk of such a latex writer on 
docutils-users... at least not in the last year.

Best Regards,

Fuzzy
http://www.voidspace.org.uk/python

>Cheers,
>mwh
>
>  
>