[Doc-SIG] A promise

[Tony J Ibbs (Tibs)]

A quick swathe of odd replies to various messages - gosh, everyone was
busy after I went home last night.

OK. We have three components to this thing:

1. Find the docstrings (and (eventually) provide information for
references 'tween them)
2. Parse the docstrings
3. Emit the documentation

As said before, it looks like I can "steal" 1, probably from Fred's code
initially (not Frank, not Frank - I'll have to write that 1000 times on
the whiteboard.). And then maybe Tools/compiler - I'll have a quick look
at that. However, as someone else said, which tool is used only *really*
becomes important when one wants cross-references to be disambiguated
correctly (unless one is willing to make up "labels" and "names" and
hope they'll match up in the wash, so to speak - rather like the way
Unix handles dynamic linking!). And I think everyone is agreed that
"importing" modules just to document them is not on.

Parsing of the docstrings is what I've been most concerned with, and is
currently using REs, 'cos that's what other things were using. It thus
won't be as powerful as it might be (at least at first), 'cos I hate REs
and don't want to write the nifty tricks one needs to do to embed strong
in italic, etc. If I had my ideal way, I'd parse the docstrings with
mxTextTools, 'cos I like them. But since I assume they're not going to
be in the standard distribution, that's out.

For 3, I'm assuming that STNG's approach of phase 2 producing a DOM
structure is sensible, and thus the tool will eventually do that (it
doesn't yet) - that should make it very easy to plug a formatter in.

As to the format itself - I like the indentation. I think people
overestimate how *much* they need to use indentation until they've
written ST[NG] a bit. I also think (and stuff seen from Jim and co.
confirms me in this - well, actually, I stole the idea) that ST[NG]
users find that the problems they come up with *in theory* don't often
come up in practise, because of the design of the thing - with the
obvious exceptions of *our* perceived need to handle code specially
in-line, and thus a need for quoting that has been able to be put off
for a while in ST. I'd write more on that if I had time (the things that
disturb me about STNG are more things like "coherence of lists" than
indentation).

*But* what I want to do is produce A Tool which can read docstrings
containing STPy (and preferably STNG as well), and produce documentation
from it. Soon. Then we can criticise and reform a body of code that
already (mostly) does the job we want, *as well as* refining the rest of
the documentation standard itself (so in a sense it's a good thing
that's already started, *provided* the tool still gets written -
although I wish there was another me to argue the format as well). As
others have said, if it misses 2.1, so be it - heck, 2.1 may miss 2.1
(so to speak).

Tibs - must dash, paid work to do
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)