[Doc-SIG] Python docs in reST

[Ian Bicking]

Felix Wiemann wrote:
>>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.

I think now is a good time for hacks, because we don't actually know 
what we're trying to create.  There's no clear model that we can point 
to, so we need to be more experimental and less worried about the 
gracefulness of the underlying implementation.  This HTML hack would be 
relatively easy to process right nwo.  And really I think it's 
justifiable that interlinking and indexing be dealt with somewhat 
separately from much of the rest of ReST, so it's not architecturally 
bad, even if the means of communication with ReST are a bit crude.

I'd be happier to see ugly code with great input and output right now, 
even if it was somewhat limited in its scope.  That would be a good 
starting place.

-- 
Ian Bicking  /  ianb at colorstudy.com  / http://blog.ianbicking.org