Generating project documentation

Documentation generation is not supported in Together Whiteboard.

Together delivers a wide variety of documentation generation options. Regardless of the option you choose, your system documentation stays accurate and up to date.

• HTML doc-gen with JavaDoc (tm) compatible output. If all you need is net-ready on-line doc that's complete and up-to-date, and quick and easy to produce and update, use this option.

• If you need doc that's readable or printable with major word processing applications, choose template-based doc-gen option using the pre-fabricated RTF template .

• If you need custom formatting to meet corporate or government standards, use the built-in Documentation Template Designer in conjunction with your custom script accessing the Together API to generate documentation.

Tip: If you're looking for information to get started fast, see Getting Started: Documentation Generation.

Generating HTML documentation

Generating HTML documentation, including JavaDoc is designed to be as simple and straightforward as possible:

• Set JavaDoc options in your default or project configuration (optional)
  

• Open the project you want to document
  

• Launch HTML docgen and select parameters.
  

• Optionally deploy generated output to intranet or Web server

Setting JavaDoc options

To set JavaDoc options in your configuration:

1. Launch the Options dialog.
   

2. Use Advanced to select the configuration level if necessary
   

3. Select the Generate HTML tab.
   

4. Expand the JavaDoc Options node.
   

5. Set JavaDoc and other options as desired referring to the on-screen Help.

Launching HTML docgen

1. On the Main menu choose Tools | Documentation | Generate HTML to launch the Generate HTML dialog.
   

2. Set desired parameter options:

   • Packages: Specify which packages to include in the output, current package only, current package plus subs, or all project packages.
     
   • Output folder: Browse to the desired target location for generated output
     
   • Include Diagrams: check if you want to generate GIF images of diagrams with imagemap links to text documentation. Tip: if you have very large diagrams, remember that some browsers do not support large GIF files. You can speed performance by clearing this option.
     
   • Navigation tree: check if you want to generate an Explorer-style navigation treeview for your documentation
     
   • Launch HTML Browser: check if you want to launch your browser and load the generated doc as soon as docgen is finished.
3. Click OK in the dialog to generate doc to the specified target directory. To view doc later, run your web browser and load the file index.html in the directory you specified for HTML output.

RTF and other template-based documentation

If you need documentation that's compatible with a word processing application, generating RTF (Rich Text Format) documentation is just as easy as generating HTML:

• Open the project you want to document
  

• Launch the Generate Documentation dialog and select the rtf template (included with Together).
  

• Set paramters and generate the documentation.

Launching RTF docgen

1. On the Main menu choose Tools | Documentation | Generate Using Template to launch the Generate Documentation dialog.
   

2. Set desired parameter options:

   • Scope: Specify which packages or diagrams to include in the output: current package only, current package plus subs, all project packages, or just the currently-focused open diagram.
     
   • Template: specify the template (.tpl) file to use to format the generated output. A number of pre-fabricated templates are provided in the directory: $TOGETHER_HOME$/modules/com/togethersoft/modules/gendoc/templates/. Choose one such as Project Report.tpl.
     
   • Output format: Choose rtf from the list of available formats.
     
   • Output folder: Browse to the desired target location for generated output
     
   • Include Diagrams: check if you want to generate GIF images of diagrams with imagemap links to text documentation. Tip: if you have very large diagrams, remember that some browsers do not support large GIF files. You can speed performance by clearing this option.
     
   • Launch Viewer: check if you want to launch the application registered as an RTF editor (Word, for example) and load the generated doc as soon as docgen is finished.
3. Click OK in the dialog to generate doc to the specified target directory. To view doc later, run your RTF-compatible word processor and load the generated rtf file in the directory you specified for output.

Automating documentation generation procedure

If you have a nightly or other periodic automated build process, you can update your documentation as part of it by having your process script call Together's HTML or RTF docgen facility through the command line interface. Together provides the possibility to generate documentation without actually opening Together window. You can use one of the launchers shipped with Together: $TGH$\bin\Together.exe, $TGH$\bin\TogetherCon.exe, or $TGH$\bin\win32\umldoc.exe (for Windows users only).

Together.exe and TogetherCon.exe allow to choose between RTF and HTML documentation, while umldoc.exe produces HTML documentation only. On the other hand, TogetherCon.exe and umldoc.exe bypass Together window, while Together.exe starts the shell and brings you through the entire doc generation procedure.

The syntax rules are outlined in the Reference | Command Line Parameters.

Examples

• Together.exe for genHTML:

Together.exe -script=com.togethersoft.modules.genhtml.GenerateHTML - sourcepath d:\Together4.2\samples\java\CashSales d:\Together4.2\myprojects\CashSales.tpr

• Together.exe for gendoc

Together.exe -script=com.togethersoft.modules.gendoc.GenerateDocumentation d:\Together4.2\myprojects\CashSales\CashSales.tpr

• TogetherCon.exe for genHTML:

TogetherCon.exe -script=com.togethersoft.modules.genhtml.GenerateHTML -browser -d d:\out d:\Together4.2\myprojects\CashSales\CashSales.tpr

• TogetherCon.exe for gendoc

TogetherCon.exe -script=com.togethersoft.modules.gendoc.GenerateDocumentation -d d:\out d:\Together4.2\myprojects\CashSales\CashSales.tpr

• umldoc.exe:

umldoc.exe -d d:\out d:\Together4.2\myprojects\CashSales\CashSales.tpr