[Doc-SIG] Python docs in reST

Michael Foord mike at pcblokes.com
Mon May 23 10:16:43 CEST 2005


Felix Wiemann wrote:

>Ian Bicking wrote:
>
>  
>
>>If the documentation is able to have intelligent interlinking, that'd
>>also be great; my experience with ReST is not great here, as it makes
>>strong distinctions between same-page links and external links.
>>    
>>
>
>Yes.  It would be nice if Docutils were able to merge several input
>documents into one, so that you could use internal links to link between
>the parts (input files).
>  
>

Surely merging input files into one output file is relatively 
straightforward ? What would be nicer (but more complex ?) would be 
generating several output files and autogenerating the cross links 
between them.

Didn't this discussion start with how to automatically include 
docstrings from source code - or have we moved on ?

Yes resolving a system for docutils that breaks the 1 : 1 dependency on 
input and output files would be nice, then you could generate contents 
pages and navigation links for multipage documetns very nicely. But I 
imagine that is going to take sometime...

Hacks in the meantime sound liek a good idea... especially as we don't 
have a clear idea of what we want the system to even *look* like. Trying 
*something* sounds like the *only* way of getting there....

Best Regards,

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

>  
>
>>Though maybe that could be easily fixed with a two-phase build
>>process; ReST identifies the links, outputs HTML, and then I resolve
>>all the links in a separate phase.
>>    
>>
>
>This is more a hack (sorry), because you'd have to mess with HTML code.
>
>A clean implementation would have to deal with multiple input files and
>multiple output files as distinct and independent concepts, i.e. you
>shouldn't need to have a 1:1 relation between input and output files.  I
>don't have enough time (and interest) to develop such multi-file support
>at the moment, though.  It may become important when we try to convert
>the standard docs to reST, though.
>
>  
>



More information about the Doc-SIG mailing list