[Doc-SIG] Python docs in reST

[Ian Bicking]

Felix Wiemann wrote:
> If you want to load not only chapters but the *whole* Python
> documentation into a document, you'd end up with unacceptable parse
> times.  To fix this, you'd need to parse all input files (without
> resolving references etc.) and store the results (namely Docutils node
> trees) in XML files.  Later, when creating the big document, the XML
> files can be read and assembled, which should probably not take very
> much time.  

Hey, now we're getting back to exactly what I suggested! ;)  Really, XML 
or rendered HTML, it's not a huge difference.

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.  Something like this:

class DelayedLinkResolver(nodes.SparseNodeVisitor):

     def visit_reference(self, node):
         if node.resolved or not node.hasattr('refname'):
             return
         node.resolved = 1

class DelayedLink(Transform):

     default_priority = 0

     def apply(self):
         visitor = DelayedLinkResolver(self.document)
         self.document.walk(visitor)

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, like:

   See foo_

   .. _foo: bar_

But I'm sure that's resolvable.  And sure, there may be a better more 
abstract way, but this is Easy Right Now, and all the subtle and hard 
problems (IMHO) are in how you express and resolve links, and this gets 
you to that problem more quickly.  Or maybe this seems ideal to me 
because I've never cared about any format but HTML (just to admit my 
biases ;).

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