[Doc-SIG] A promise

[Laurence Tratt]

"Tony J Ibbs (Tibs)" wrote:

> If we don't have a solution for Python 2.1, I will be sad, but not
> devastated. On the other hand, if we don't have a solution for 2.2, I
> shall be angry.

Missing 2.1 wouldn't trouble me personally, although I agree 2.2 is a realistic,
sensible target and gnashing of teeth would be the result of missing that
particular boat.

>>> 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>. 
> On this one you undoubtedly have more experience than me, but I would
> *like* to be able to use the same tool for 1.5.2 as for later versions
> of Python, even if in a less sophisticated manner - there are a
> significant number of firms (read one, the one I work for!) who have
> only just gone up to 1.5.2 (from 1.3 - can you say "hurray!" - is Eddy
> watching this?) and aren't likely to go up again soon.
> 
> But again, I won't weep too much if that isn't feasible.

You have three main choices as to how to examine the Python code and work out
where the docstrings are (the docstrings themselves are something seperate and
probably easiser to deal with):

  1) Use Pythons built in parser
     Pros: 100% accurate; already exists
     Cons: Tracks the current release (or, at least, the last time the
             grammar changed)

  2) Create another parser with eg Spark
     Pros: Decouples from Python version
     Cons: Probably slower; argument inducing over which system to use;
             creating and maintaining a seperate grammar can be hard

  3) Parse using regular expressions or similar
     Pros: Decouples from Python version; no need for a parsing system
     Cons: Completely crap, buggy way of doing it (I investigated it for
             feasibility once. It isn't)

In my opinion, with this type of tool "less sophisticated" can too easily mean
"not worth using". You have to go the whole hog in nearly every aspect otherwise
you'll end up with a half-arsed system and we have enough of those already.

Having said that, some things - like creating a sane mechanism to allow the user
to denote private variables - are not necessary and if not present won't detract
from the overall experience.

> The thing will probably come as an "STNG-clone" supporting class with a
> pre-built example of extending it to be "our tool" ('cos that's a fairly
> easy way to do it and to make it possibly more useful for Zope-readers).

I am slightly confused over your initial aim: are you inteding to produce a STNG
parsing module on its own, first or do you intend creating a system which
contains the STNG module as part of it? Now I'm worried we're talking at cross
purposes!


Laurie