[Doc-SIG] A promise

[Laurence Tratt]

"Tony J Ibbs (Tibs)" wrote:

> OK. Here is my proposal and promise.
[snip]
> 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.

In my opinion, trying to rush this for the sake of speed alone is likely to
create a bad tool which will alienate people to the point that noone will want
to *ever* use the tool - a bad initial release can put people off even when the
tool becomes useable. By all means develop *alongside* Python, but wanting to
get something - no matter how good or bad - into the distribution isn't the way
to get everyone to play along. It'll look unprofessional to include crappy
software alongside a main Python release.

You might be able to get something out by March (when I wrote Crystal, most of
the work was done in 2 months and that includes things that wouldn't be
necessary for a tool that is only intended to deal with Python) but there again
you might not. When you're relying on peoples spare time - as this likely will -
playing with release dates is like playing with fire.

> 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!)

Bad idea. IMHO, the only way to create a professional tool is to get it to use
Pythons parse trees ("import"ing the modules is at best mickey mouse even if it
solves one or two problems that static analysis can't hope to) and that really
means that the tool has to track the latest release. As you seem to want to tie
it to the main release anyway, this doesn't seem like a problem <wink>.

> 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!

There's a demo of how to munch the parse trees in the main distribution - it's
what I started from.

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

I doubt nicking this component is feasible.
 
> 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?

Yes and no. If what you're producing will be extendable enough to become the
perfect tool, yes. If it's not extendable enough and is going to be another
brick on the way to creating the perfect tool, I wouldn't bother - current
bricks include gendoc, pythondoc, Crystal, pydoc and happydoc. We have enough
"nearly" examples to go on.

> .. [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.

You might run into what I did - people actually seem surprisingly disinterested
when a tool is actually produced. I know - I produced such a tool and it's
probably extendable enough to cope with all this stuff <wink>. "Maybe this
time"... but we've seen that several times before and people seem to get less
interested as the discussions get increasingly anal and removed from getting
anything done which is what's always happened before - a hint maybe for me to
wrap this message up <wink>.


Laurie