[Kss-devel] Development tools

[Balazs Ree]

On Sat, 09 Jun 2007 11:06:25 +0200 Jeroen Vloothuis wrote:

> To make development with KSS a bit nicer I was thinking of adding a few
> features.
> 
> The first feature would be a listing of the available commands. This
> could be implemented as a simple Javascript function which displays all
> commands with their documentation.
>

We have been long planning a feature that ends up similar to this, and 
although it's not written yet, I discussed it in details with a lot of 
developers including you. So I would expect you to remember it, but maybe 
I did not make myself clear enough when we talked about the last time in 
April. Anyway I am writing you a bit about it now but it's a long planned 
feature with more than I could detail in a single mail.

This was called maybe the "docstring feature" but there was no 
established name for it yet. It is quite high priority for me personally, 
the main reason for not starting on it is because while we cannot fulfill 
our more burning obligations like fix Plone bugs, we cannot start giving 
resources to a "nice to have" feature. Nevertheless I support the idea to 
start working on this on an upcoming sprint and I already planned it for 
the Snowsprint, and also for Potsdam (where I could not attend in the 
end), but there was not enough interest between the developers to start 
with it really. 

Some differences between your proposal and the original proposal is, that

- we want to handle both documentation and registration metadata, and

- we don't plan to do the mechanism that delivers this information from 
javascript. Instead we want to store the data itself inside the 
javascript, but deliver it from python.


The original idea was this:

We want to have something that is like how the dosctrings function in 
python. For this we need to establish a documentation standard that is 
both pythonic and also fits the java world.

This way the javascript plugins would become self documenting. They would 
contain comments blocks next to the plugin registrations. This would 
document the given function (action, provider, selector, eg. everything 
that is extensible) probably in ReST. In addition it would contain rich 
metadata that would describe

- the identification (type and name of the plugin)
- mandatory and optional parameters to default value
- and every other information that we currently register from zcml.

This way all the documentation and registration information would be in 
the javascript, close to the actual code it documents. Instead of the 
number of the zcml directives we would have a *single zcml directive* 
that defines a javascript file as a plugin. Then it would parse the 
docstring information from the file and build up the registration 
database on the server side so we would have the same data available as 
currently but without the need for registering both on the client and on 
the server redundantly.

In addition we would have a plain python api and a commandline for the 
same task. This means that any other server side (non-zope or even non-
python) could use the same extractor to fetch the necessary information.

One of the use of the fetched information (as currently) is doing early 
semantical checks on the server like disallow marshalling nonexistent 
commands, and the second is to offer the documentation from the server. 
>From zope this would be on-line rendering of the plugin documentation 
from a view, presented from a document tab somewhere. For other systems 
we can build a set of static html pages that can be served up to the 
client.

To avoid a misunderstanding, we do not, by no means, want to generate any 
javascript code. The javascript plugins would be registered as before, 
only their usage would be annotated in the docstrings next to them.

The original idea as described above was for the self-documenting of the 
plugin javascript. At the time when this idea was born, we did not yet 
have the commandsets, so it did not cover then. But obviously the same 
can be extended to the commandsets either, to have the documentation of 
them available. This would even be esaier since parsing the python does 
not require a separate parser. However also together with this, as a 
separate but connecting task, we would want to standardize the loading of 
the commandsets for zope and plain python as well.




About the actual tasks that are needed to start with first, we would need 
two things:

1. Design the actual documentation format. If we use ReST, there is 
chance that we can describe the metadata als with syntax already existing 
in RsST. We have to investigate if this is possible.

2. Find a parser builder in python. I did some research that included 
about six python parser builders but I could not settle on any of them. 
As a direct goal, we need a parser because we need to extract the 
comments out of the javascript. Even just this is far from trivial, and 
imo, instead of doing complex regexp magic, we need to choose one of the 
available parser builder libraries. 

Both these two are tasks that we could typically do together, on a 
sprint. Maybe a bit separate task is to have code that extracts the 
comment blocks from js, this could be dome before the sprint. 


> Because KSS is a pluggable framework a developer can then easily see
> which command's are available for the chosen platform. Something like
> this would help Plone developers because there are/might be a few
> specific Plone commands.
> 
> Using a self documenting feature means you will always have the proper
> documentation.

So as I described above, this is planned to be provided, and even more.


> Another feature would be to have some interactive prompt support.
> Currently Firebug already provides us with a console. It would be great
> if we could use this to execute something like:
> 
> kssApplyRule('a.special:click { ... }')
> 
> kssClearRules()
> 
> Does anyone else see value in these ideas?

Would be nice to think about this, except that kssClearRules is not 
possible currently with the kss core. Again I do not want to go deeper 
into this, just briefly:

Clearing rules would be a desirable feature. It would require however 
that the physically bound browser events can be cleared. This is not 
supported by DOM/BOM, only posible if we have already depended on one of 
the javascript frameworks or use custom code.

Even after this, it would require a significant rewrite of the kss core. 
One of the main challenges is, how to implement the rebinding of nodes 
when a html class changes. Ie, this is the main feature where clearing 
of  events would become necessary. However in the worst case such an 
operation, unfortunately, may degrade to rebinding all the rules in a 
page. I don't want to go deeper into this, realistically this is not 
something we will have soon, but it could come after wa have completed 
the other four or five planned/ongoing "nice to have" projects.

However the kssApplyRule would be feasible.


What would be, however, even more interesting and even more feasible, is 
write introspection utilities for kss, to provide a way to see which 
rules are bound where. In the end we could arrive to FireBug where you 
can introspect kss similarly the way you can introspect html nodes.


--------------------------

Summarizing, both features you raised are important on the long term 
however they involve pretty complex details, and we have much higher 
priority tasks at the moment that we must complete first for the success 
of kss. Nevertheless we need to start planning these things in parallel, 
but since there has been lots of brainstorming done on these issues 
already, and that they involve the deep knowledge of the core code, I 
find it inevitable that we start working on these issues together, during 
a sprint.

-- 
Balazs Ree