[Doc-SIG] DPS and DOM trees

[Tony J Ibbs (Tibs)]

I've now got to a stage with dps_visit.py where I'm starting to play
with actually integrating DPS/reST into it. Yes, I know it isn't
finished yet (!), but I want to flesh out what it's going to do before
fining it down (putting that another way, I want to see some HTML output
from what I'm doing, and that means generating a DOM tree first).

This leads to a question/comment or two...

Firstly, the DOM support in dps/nodes.py is bound fairly strongly to
minidom. This has the advantage (to the user) that they don't have to do
anything particularly special to get a DOM tree (a few lines of code,
nicked from restructuredtext/tools/quicktest.py will do it), but it has
the downside that one *is* tied to minidom. I could well imagine someone
using 4DOM (for instance) wanting to cache the DOM trees for a variety
of Python modules - rather as Unix systems sometimes cache the results
of parsing man pages. Or wanting to do queries on the tree that minidom
doesn't provide support for.

I would thus like to propose that the user provide a DOM document
instance to the DOM generator methods - this allows them to derive that
however they like, and we can document which methods we require (the
writexml method is called outwith this context, so we can assume it's
being used by a caller who already knows which DOM system is being
used).

As a fallback position, one *might* make minidom the default - but I
prefer explicitness here, I think.

Secondly, the current nodes.py assumes that the document produced will
map to a single docstring - or at least so it look to me (after a short
time reading it, admittedly). This is a disadvantage if one is trying to
produce a DOM tree with (for instance) a Python module as the "top" of
the document tree, and docstrings hanging off various points.

Luckily, if the user is required to provide the DOM document to the
code, then this problem goes away - one just adds children to the
relevent element in the tree.

If these ideas seem sensible, would it be a Good Thing for me to work on
my own version of nodes.py, and integrate it back in later on (bearing
in mind my CVS-lessness)?

Thirdly, and separately, do we intend to support Python 1.5.2, or are we
starting support with 2.0? Whilst I think it was important that pydoc
worked for 1.5.2, I'm less worried for this - although it isn't *hard*
to do it, it may be inconvenient (although I'm still working with 1.5.2
at work, alas).

Tibs (who narrowly avoided starting to write docstrings for existing
code last night, instead of writing new code)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)