[Doc-SIG] Python docs in reST
Ian Bicking
ianb at colorstudy.com
Wed May 25 23:28:58 CEST 2005
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
More information about the Doc-SIG
mailing list