[kepler-dev] Documentation updates

[Christopher Brooks]

Hi Kevin,

I've been working with Edward on some of the documentation system
details.  I'm a little fuzzy on the details, but below is my
understanding.

The basic idea is that we now have ptII/doc/doclets/PtDoclet.java that
reads java files and generates xml using the DTD at
ptolemy/vergil/basic/DocML_1.dtd.  These .xml files currently reside in
ptII/doc/codeDoc, (though they will likely move elsewhere).

Running (cd $PTII/doc; make docs) creates the .xml files in
ptII/doc/codeDoc.  Currently, we only generate .xml files for java
files that extend NamedObj.

There are at least two types of documentation here:

1) Atomic actor documentation generated from the javadoc.  Perhaps
over time, this documentation will be edited and lose its connection
to Javadoc, but it seems like this is a start.  This documentation
resides in separate .xml files from the actor.  I think this is fairly
static, only actor authors and domain experts are likely to edit it.
Initially the only way to edit it is by updating the .java file, but
this could perhaps change.

2) Custom atomic and composite actor documentation edited by users.
Currently, these changes are residing in the MoML file for the model.
Yes, this will result in a larger files and slower parsing.  In the
short term, we should probably live with it.  In the longer term, we
need to consider whether Kepler should change so that it does lazy
loading.

Note that if the user adds a port to an actor and then documents it,
then this documentation would be in the moml file for the model
Also, composite actor documentation would be in the moml file for the
model.
Perhaps we could put this documentation in a separate file, but
if we do, we run the risk of the documentation becoming separated
from the model.


The design is certainly open for suggestions, below are some ideas.

* I don't know much about the kar format, but I'm thinking that we
could put the PtDoc generated .xml directory in the kar file?
Would this slow down start up?

Perhaps for Ptolemy, which does not yet have the kar format, we could
put the .xml in a subdirectory?  So ptolemy/actor/lib/Ramp.java would
have ptolemy/actor/lib/Ramp/Ramp.xml.  It seems like this would
conflict with the Kepler layout, so we could call it Ramp.docxml or
Ramp.doc.xml or something.

I'm also thinking we should move the Ptolemy actor icons in to the
subdirectory.

Basically, I'd like to start moving Ptolemy in the direction of
being able to use the .kar files without actually requiring it yet.

      
* Also, it would be cool if the documentation system had an
easy way of showing us other demos that use this actor.
It seems like the Kepler search mechanism could possibly be extended
to provide this.  Maybe it already has it?

As an alternative, we could generate the index when we updated
the actor documentation.

I wrote code that will generate a list of all the demos on the main intro
page and on one page down.  We could traverse those models and
create an index of actors.  If need be, we could limit it to
the first 20 examples or something.

Ptolemy classic had a similar index.  I found it to be very useful
because it allowed me to see how other people had used a specific
actor.

_Christopher

--------

    
    Nandita,
    
    I think the end state is to have a deliverable .kar file which is 
    completely self contained.  That is it has the bytecode, the moml, and 
    supporting "static" information like documentation.  The format and 
    functionality of this beast has yet to be defined, but given that this 
    information is intended to be delivered as a unit I don't think there 
    can or should be any way for the end-user to update it.
    
    Storing the documentation in the moml might not be such a good idea.  
    Given the current situation of parsing all the moml for all the actors 
    on Kepler startup, having the documentation in the moml cause the kepler 
    runtime memory requirements to be very much larger than they currently are.
    
    Since we plan on using classloaders to find the various resources for 
    the actors, I think it would be best if the documentation were a 
    seperate file distributed in the kar with the actor.  The moml would 
    then contain the name of the resource.
    
    Matt or Chad might have other insights which could allow this functionality
   .
    
    Kevin
    
    Nandita Mangal wrote:
    
    > Hi Kevin,
    >
    > As with the recent changes in the documentation infrastructure in 
    > Ptolemy ( editing & storing the custum documentation  in a MOML file) 
    > , I was wondering if one can also implement the "GetDocumentation" 
    > feature in Kepler & store new results in the actor's moml file ? Could 
    > you also suggest  possible implementation changes/issues with the 
    > above structure in Kepler.
    >
    > Thanks!
    > Nandita.
    >
    >
    > Edward A. Lee wrote:
    >
    >> Ilkay:
    >>
    >> This is exactly what happens now... Drop in the Documentation attribute
    >> and double click on it, and you get a form for filling out documentation
    >> fields (overall description, author, documentation for each parameter
    >> and port, etc.).  The form is customized to the actor (you get fields 
    >> for
    >> ports and parameters that exist...).
    >>
    >> Edward
    >>
    >> At 03:55 PM 1/2/2006 -0800, Ilkay Altintas wrote:
    >>  
    >>
    
    _______________________________________________
    Kepler-dev mailing list
    Kepler-dev at ecoinformatics.org
    http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
--------