[Doc-SIG] Python docs in reST

Felix Wiemann Felix.Wiemann at gmx.net
Thu May 26 00:14:41 CEST 2005

Ian Bicking wrote:

> Felix Wiemann wrote:
>> [Big document from many input files:] you'd need to parse all input
>> files (without resolving references etc.) and store the results
>> (namely Docutils node trees) in XML files.
> Hey, now we're getting back to exactly what I suggested! ;)  Really, XML 
> or rendered HTML, it's not a huge difference.

Oh, it is.  :-)

Given a proper serialization algorithm, you could cleanly deserialize an
XML file into the original node tree, which is not possible with HTML.

> So, back to that expedient solution I talked about before, you can
> fairly easily get docutils to not try to resolve any links at all,
> outputing some marker that indicates this.
> [...] Then later you look for <a refname="XXX">...</a>, where refname
> contains the simplified link name (e.g., `This Link`_ becomes <a
> refname="this-link">This Link</a> in the HTML).  There's a chance this
> will break with indirect links [...] But I'm sure that's resolvable.

I fear you'd end up re-implementing Docutils' reference-resolving
system.  I had to work with it once before, and trust me, it's quite a
complicated beast.

I wouldn't say a hack which does what you described would be a bad thing

For private mail please ensure that the header contains 'Felix Wiemann'.


More information about the Doc-SIG mailing list