[kepler-dev] Documentation updates : Adding documentation to Kepler Actors

[Nandita Mangal]

Hi,
As we all know ,Kepler actors currently need some form of  documentation.
I have written a basic application (using xslt) , which gathers all 
actor MOML files and  produces formatted HTML pages (which the Kepler 
users can view as a basic source of documentation for now).
As a future goal, I agree that documentation can be divided among 
users/developers and made more comprehensive (adding javadoc links etc), 
however currently this documentation framework gives some basic 
information on Kepler actors. ( If the developers fill their respective 
actors docs , we can have a basic documentation structure ready, to put 
on the website  :-) )

The framework can be divided into 2 steps:
1) Editing the current actor XML files (src/actors) to add more 
documentation information.
2) Creating HTML pages from the above XML files.
_
*Editing the Actor XML files (src/actors) to include documentation*_
This can be done a number of ways
1) /Currently Implemented Way/:  (Command Line Input) . A Java form like 
GUI pops up from build file , asking for information on 
actor/authors/projects etc.  and further edits the required actor MOML 
files. <attached screenshots: selectActorToDocument.JPG   , 
customizeActorDocumentation.JPG  >
2) /Possible Future Implementation: /(Online input) . A developer can 
edit the actor documentation online, provided the CVS repository files 
are made available online. This was the initial way discussed between 
Ilkay, Efrat and I , however the above web application requires cvs 
files access & editing features from online. Need more  discussion on 
best way to implement this. Christopher also had mentioned about this 
(as a wiki actor documentation input page/php) in "ActorDocumentation" 
emails.
3) /To be Implemented Way/: ( Customize Documentation from canvas as 
well, like Ptolemy )
*
_Generating Documentation HTML pages_*
A straightforward way of creating well-formatted output, via stylesheets 
and actor xml files as input <attached screenshots: finalDocumentation.JPG>


_Features of the above framework_
1) Can edit multiple actors in one session.
2) Fairly quick generation of HTML (as its  xslt  transformations)
3) Gives an interface to editing documentation from command line (along 
with canvas)

_Features to be implemented/improved_
1) Online interface to edit documentation.
2) Depends on developers local src/actors files right now . And hence 
need that developer has updated src/actors folder. (this is where online 
interface/ php would be useful)
3) Making the framework ,have more useful features such as  javadoc 
links,link to code.
4) Error Recovery on empty/invalid src xml files or invalid input.

If future library framework decisions make actor documentation in 
separate files /separate locations, the framework can be re-adjusted 
accordingly.
(as long as xslt can take new documentation files format as input)

The above framework would be in kepler-docs/dev/documentationFramework. 
In 
kepler-docs/dev/documentationFramework/documentationFrameworkTutorial.doc 
(pdf)
there are steps on how to edit documentaiton and generate pages.

The above is still a basic framework and I agree needs more 
features.Looking forward  to  any suggestions/questions/comments.

Thanks,
Nandita.


Edward A. Lee wrote:

> At 10:55 AM 1/6/2006 -0600, Kevin Ruland wrote:
>
>> Edward,
>>
>> You have thought of everything.  It seems that there should be no 
>> difficulty here.  I do have some questions:  The DocML file, is it a 
>> seperate file or is it embedded in the actor's moml file?  Is it 
>> possible to call the rendering tool using an open InputStream rather 
>> than a filename?  This will enable us to track down the DocML file 
>> using ClassLoader.getResourceAsStream().
>
>
> The DocML file is a separate file.
> It is opened using exactly the same mechanism that is used to open
> any file from Vergil, so you can open it via the File menu, via a 
> hyperlink,
> or via the "Get Documentation" context menu, and all three yield the same
> display of the docs.
>
> When you override docs in an instance, the information is not stored
> in DocML at all, but rather as an instance of DocAttribute, which 
> contains
> one attribute corresponding to each DocML element.  This neatly avoids
> the problem of trying to nest two distinct DTDs within one XML file.
>
>
>> BTW - I do have to agree that well written class documentation is 
>> useful to both developers and users.  My experience with reading and 
>> writing javadoc is it tends to be quite brief and sometimes very 
>> confusing.
>> Let's hope at least this piece of javadoc can be well written.
>
>
>
> I agree... Hopefully making the docs more visible this way will encourage
> actor developers to create decent docs.  E.g., right now, it is very
> obvious if no documentation is given for a port or parameter...
>
> Edward
>
>
> ------------
> Edward A. Lee
> Professor, Chair of the EE Division, Associate Chair of EECS
> 231 Cory Hall, UC Berkeley, Berkeley, CA 94720
> phone: 510-642-0253 or 510-642-0455, fax: 510-642-2845
> eal at eecs.Berkeley.EDU, http://ptolemy.eecs.berkeley.edu/~eal  


-------------- next part --------------
A non-text attachment was scrubbed...
Name: selectActorToDocument.JPG
Type: image/jpeg
Size: 141706 bytes
Desc: not available
Url : http://mercury.nceas.ucsb.edu/ecoinformatics/pipermail/kepler-dev/attachments/20060130/22188099/selectActorToDocument-0001.jpg
-------------- next part --------------
A non-text attachment was scrubbed...
Name: customizeActorDocumentation.JPG
Type: image/jpeg
Size: 53610 bytes
Desc: not available
Url : http://mercury.nceas.ucsb.edu/ecoinformatics/pipermail/kepler-dev/attachments/20060130/22188099/customizeActorDocumentation-0001.jpg
-------------- next part --------------
A non-text attachment was scrubbed...
Name: finalDocumentaion.JPG
Type: image/jpeg
Size: 189015 bytes
Desc: not available
Url : http://mercury.nceas.ucsb.edu/ecoinformatics/pipermail/kepler-dev/attachments/20060130/22188099/finalDocumentaion-0001.jpg