Actor and model documentation system

Primary Authors: Edward A. Lee, Christopher Brooks.

Actor and model documentation is displayed using custom widget. The documentation for an actor or model can be edited by the user. To view the documentation for an actor, right click on the actor and select Documentation -> Get Documentation.

This functionality is implemented using DocTableau and other classes in vergil.actor and the PtDoclet doclet.

Building the documentation

When the documentation system is invoked on an object, the documentation system checks for documentation file that must be present.

If the application is run from a prebuilt Windows installer, then the documentation usually need not be built. If the application was built from sources, the documentation files will need to be created.

If the documentation system is missing its files, the the Doc Builder window will come up. To rebuild the documentation, view the documentation on any actor, attribute or director, right click on the object, select Documentation -> Get Documentation and then select Build -> Build docs in the Doc Viewer. The Documentation Builder will requires that $PTII/configure was run so that the system knows which packages are present.

If you are building from source, then you can either use the Documentation Builder as above or run:

      cd $PTII/doc; make docs
    

How the Indexer works

If $PTII/doc/mk/ptII.mk is present (say by running ./configure), then the indexer is run by running make docs in $PTII/doc. If ptII.mk is not present (this is common under Windows or with Eclipse), then the javadoc command is run.

Both methods first run javadoc and then invoke ptolemy.moml.filter.ActorIndex, which read in two files:

$PTII/doc/codeDoc/allNamedObjs.txt

All the NamedObj files that were seen while running the doclet defined in $PTII/doc/doclets/PtDoclet.java. This doclet is run while running make in $PTII/doc.

$PTII/ptolemy/configs/doc/models.txt

The names of all the demonstrations in $PTII/ptolemy/configs/doc/completeDemos.htm.
This file is created by running

	  cd $PTII/ptolemy/configs
	  make
	

That rule runs HTMLAbout.main() which creates models.txt.
Note: models.txt need only be updated if $PTII/ptolemy/configs/doc/completeDemos.htm changes.

ptolemy.moml.filter.ActorIndex reads these two files and creates .idx files in $PTII/doc/codeDoc.