[Doc-SIG] A promise

[Tony J Ibbs (Tibs)]

We have had several rounds of the Doc-SIG, each of which starts with a
proposal, sounds like it might be getting somewhere, and then bottoms
out when pedantry about *exactly* what we want sets in. I'm one of the
pedants...

This time round, we have agreed that something *very like* STNG is
exactly what we want, and have now started to worry about the details.

(NB: I *still* haven't read any of David Goodger's stuff, even though a
quick flick through makes it look as if it has lots of good points, at
least two of which I would want to take on board.[1])

You should already be able to see what I'm worried about...

OK. Here is my proposal and promise.

1. We are going with something "very like" STNG(the specification). We
said that already. Specifically, since STNG(the code) *will* be
extendable by subclassing and customisation (heck, *is*), I believe that
whatever we choose to do *will* be doable with STNG(the application),
when it is finished (and that is a Good Thing).

2. We want to get the solution into Python 2.1, which means we need to
get *something* going soon - not least so people can try it and get any
bugs out.

3. The something we get going need not be the correct, perfect final
solution - it need only cope with *enough* of the problems to get doc
strings going (and issues of larger documents and tidying up and even
slight incompatibilities can be coped with later on). This is a Very
Important Point.

4. We need a tool that runs with bog-standard Python (preferably 1.5.2,
since that's "old technology", and also 'cos it's what I've got
available at work and at home!)

5. It's trivial to cope with Python "doc test" paragraphs (really,
really trivial), and it's not hard to cope with things like::

    This is some text
    1. This is a list line
    2. This is another
       ii. So is this

(i.e., making the list items separate paragraphs, even without blank
lines) - and I think those two cover 80 or 90 percent of the "wish it
were better" for Python users.

(Actually, pedantically, I'm not entirely convinced one needs them to be
separate paragraphs, so long as they get to be separate nodes in the
tree, but paragraphs are traditional...)

6. The likely solutions ALL provide base classes which can be subclassed
and customised to get the parsing and output solutions that are wanted,
so we can later on fritter away time on extended versions of the process
with complete ease.


I keep grumbling about not having any time, but here's a promise:

I will have something simple available by Christmas that will:
  a. find docstrings in a module
  b. parse them
  c. emit something useful (which will be HTML initially
     'cos it's dead easy)
  d. be easy to extend and customise

'b.' is partly there already, and I shall aim to get a tidied up version
of it on the web by the end of the week (I *do* want the docstrings to
tell the truth!).

'a.' will get nicked from somewhere else, or someone else can give it
me!

'c.' might well be nicked as well, but is easy enough to do.

The solution won't necessarily be elegant, most definitely won't be fast
(except by accident), and it will have some severe restrictions (you
probably won't be able to do '*This is emphasised and **this is nested
strong***', which is what *I* call a severe restriction!), but it will
be there, and it *will* explain how to extend itself.

Is this a Good Thing To Do?

.. [1] David says "the specification must preceed the code". I agree,
but in practice specifications are normally vague (and if they're not,
they normally get changed as time proceeds). I think it is valuable to
get a tool "fleshed out", since the bulk of the tool will not change
even if major details of the spec do - once we've agreed to be based
around ST[NG] we're already most of the way there. So refining of the
spec can proceed in parallel.

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)
[I've read it twice. I've thought it over. I'm sending it anyway.]