| |  | |
| | |
| | OJBDoc is an application that will read an OJB repository xml file, analyze it and then inserts documentation into an instance of the Confluence wiki. |
| | |
| | h2. Requirements |
| | |
| | * Python 2.4 |
| | * [Cheetah Template System|http://sourceforge.net/project/showfiles.php?group_id=28961] (library) |
 | | * [CSE Configuration Manager|howto:cse utils old] (library) |
| | | * [CSE Configuration Manager|bouncer:cse utils] (library) |
| | * [Graphviz|http://www.graphviz.org] (application) |
| | * rsync (application) |
| | |
| | This application has only been tested on Linux. |
| | |
| | h2. Installation |
| | |
| | # Install Python, the dependent libraries and dependent applications. |
| | # unzip and install the OJBDoc application into a target directory |
| | # edit the OJBDoc.conf file to reflect the desired Confluence username, password and space. |
| | |
| | |
| | h2. Usage |
| | |
| | OJBDoc is a command line utility. |
| | |
| | {code} |
| | lohnk@glacier:~/project/ojbdoc/000/ojbdoc> ./OJBDoc.py --help |
| | This routine runs through an OJB-repository file producing and inserting |
| | pages documenting the database into an instance of Confluence |
| | |
| | -C, --clearAllComments |
| | clear out all persistent comments |
| | -c, --config |
| | specify the location and name of the config file (default: ./OJBDoc.conf) |
| | -b, --confluencePassword |
| | the password of the Confluence User (default: ) |
| | -A, --confluenceSpace |
| | the name of the space to be used in Confluence (default: ) |
| | -a, --confluenceUserName |
| | the name of the Confluence User (default: ) |
| | -x, --confluenceXMLRPCPath |
| | the URL for Confluence's XML-RPC service (default: http://localhost/rpc/xmlrpc) |
| | -d, --diagramsURL |
| | the base url for the images (default: ) |
| | -?, --help |
| | print this list |
| | -i, --indexPageName |
| | the name of the index page to be used as the root page (default: Database Model) |
| | -m, --moduleList |
| | a quoted space delimited list of modules to include. An empty list selects all modules. (default: ) |
| | -n, --noDeploy |
| | if present, this flag prevents updating of Confluence (used in debugging) |
| | -r, --repository |
| | location and name of the repository file (default: ./OJB-repository.xml) |
| | -R, --rsyncDiagrams |
| | a location to put the images in the form useful to rsync \[user@]host:destination |
| | -s, --sourceCodePath |
| | the base path of the source code (default: ./) |
| | -t, --templateFilePath |
| | the path to the template and abbreviation dictionary files (default: ./) |
| | -v, --verbose |
| | print what's going on |
| | |
| | {code} |
| | |
| | Any of the long option names can be included in the configuration file or provided as environment variables. Options listed on the command line override the configuration file. The configuration file overrides options that came from the environment. |
| | |
| | h3. --clearAllComments |
| | This application produces documentation in Confluence that can be annotated. A Confluence user can edit the generated pages by adding text to any table cell with "Comment" as the header. In addition, the space between any outline numbered header and a table or inset below it is also editable. These comment areas are preserved between runs of OJBDoc. This option overrides that preservation and clears the comments. |
| | |
| | h3. --config |
| | This specifies the location and name of the config file. It defaults to ./OJBDoc.conf |
| | |
| | h3. --confluencePassword |
| | The password to allow OJBDoc to log in to Confluence. While this option can provided in the configuration file, some may prefer to require it provided at run time via the command line. |
| | |
| | h3. --confluenceSpace |
| | The name of the space in Confluence that should receive the inserted pages. |
| | |
| | h3. --confluenceUserName |
| | The log in name to use when connecting to Confluence. |
| | |
| | h3. --confluenceXMLRPCPath |
| | This is a URI for Confluence's xmlrpc interface. Generally, this is in the form of http://localhost/rpc/xmlrpc |
| | |
| | h3. --diagramsURL |
| | OJBDoc generates simple ER diagrams for each table and its immediate relations. Because Confluence 1.3.x does not have an xmlrpc interface for attaching documents to pages, these images will have to live elsewhere. This option gives the base URL fragment used to specify the location of the images. |
| | |
| | h3. --indexPageName |
| | This is the name of the page within Confluence that is to serve as the index |
| | |
| | h3. --moduleList |
| | This is a quoted, space delimited list of path fragments from class names. As OJBDoc moves through the OJB-repository.xml file, it only considers classes that contain path fragments from this list. If the list is empty, it will document all classes that it encounters. |
| | |
| | h3. --noDeploy |
| | Primarily used in debugging, this option prevents OJBDoc from actually logging into Confluence. |
| | |
| | h3. --repository |
| | The location and name of the OJB repository file. This must be a valid xml file and not an xml file fragment. |
| | |
| | h3. --rsyncDiagrams |
| | The location to put the diagrams since they cannot be automatically attached. The string should be of the form \[user@]host:destination which will be passed directly to rsync as the destination. Because rsync generally requires authentication and there is no opportunity to provide such, a mechanism such as sshagent should be used to provide authentication. If no value is given to this option or this option is not present, the application will not copy the diagrams. |
| | |
| | h3. --sourceCodePath |
| | This is the path for a local copy of the source code so that OJBDoc can quote references. |
| | |
| | h3. --templateFilePath |
| | Internally, OJBDoc uses Cheetah templates to create the text of each inserted Confluence page. This option gives the path to the template files. |
| | |
| | h3. --verbose |
| | This program can take considerable time to run. This option makes the application periodically output what its doing to assure the user that it isn't just spinning its wheels. |
| | |
| | |
| | h2. Limitations |
| | This application was written for a specific project and then enhanced for use in the Kuali project. As such, it is pretty specifically taylored for the situtations it was likely to encounter in those projects. |
| | |
| | # This program handles only simple table relationships. It has not been designed for or tested on some of the more exotic table/class relationships that OJB is capable of supporting. This includes aggregation and subclassing. |
| | # Confluence does not have an xmlrpc interface for attaching files to pages. Therefore the images produced by this program will have to manually loaded into Confluence or hosted on an external web server. |
| | |
| | |
| | h2. Internals |
| | [the repository internal representation|OBJDoc Repository Document] |
