Generating documentation

You can generate reference documentation for the artifacts in your modules, mediation modules, and libraries.

To generate documentation, follow these instructions:

  1. In the Business Integration view, select the projects or artifacts that you want to document.
  2. Click theGenerate Documentation button Generate Documentation button in toolbar in the toolbar, or right-click an artifact to select Generate Documentation in the context menu. The Documentation Generation wizard opens.
  3. In the Documentation Generation wizard, specify Author name, Documentation title and a Location for the PDF file that will be generated. The default file name is reportFile.pdf and the default location is in your workspace. In any of the fields for this wizard, press F1 (Ctrl+F1 for Linux®) to get help for that field. Use the Tab key to move the focus to the next field.
  4. You can accept the defaults and click Finish to generate the documentation. However, if you want to select additional resources to be included in the output or change the layout of the documentation, click Next .
    Note: If the Finish button is not enabled, you have selected a resource that the documentation generator does not support. You must click Next to create a new master file. Then, later, you will be able to select a resource that the documentation generator does support. See "Documentation of resources" under related concepts for additional information about the documentation functions.
    1. In the Select Content page, you specify if you want to further customize the content of the generated output.
      • Select Generate documentation from the selected resource if you do not want to add or remove resources for the documentation generation.
      • Select Generate documentation from an existing master file and a master file to rerun a previously saved resource profile.
      • Select Create a new master file to add or remove resources for this documentation generation.
      See "Documentation of resources" under related concepts for additional information on master files. Click Next.
    2. In the Documentation Resource Selection page, you can add and remove resources for your documentation. Select a resource and click > to add it to the Document input resources table. You can also select items in the table and click < to remove content from the documentation to be generated. Select the Include referenced files check box to also generate information for artifacts that are referenced by the selected resources. See "Documentation of resources" under related concepts for additional information on referenced files.

      The Save As button saves the new master file so that you can regenerate the same report using the master file. Click Next.

    3. In the Layout Settings page, select the documentation layout that you require and click Finish to generate the documentation.
      Note: If you change the layout and style settings, they are saved for all subsequent documentation generations, until they are changed again.
      (To add new fonts to use in the documentation, see the instructions below.)
  5. Look for the PDF file in the location that you specified and open it with Acrobat Reader.

Adding fonts

Default fonts are specified for you, but if you want to customize the appearance of your reports, you can change the fonts used for various text entities. If you want to change the fonts that are used in the generated documentation, launch the Documentation Generation wizard and click Next until you have the Layout Settings page:

Layout Settings page of the Documentation Generation wizard

Then follow these steps:

  1. Select the Overwrite Default Fonts check box. The Fonts button will be enabled.
  2. Click Fonts and the Documentation Style Settings page opens. Change fonts as required. If the font you want to use is not available, continue to step 3 to add a new font.

    Documentation Style Settings page

  3. Click Manage fonts and the Manage Documentation Fonts window opens. Use the buttons to add fonts to the list or remove them from the list.

    Manage Documentation Fonts window

  4. Click the Add button. The Add Documentation Font window opens.

    Add Documentation Font window

  5. Click Browse to get the Open window and locate the TTF or TTC file and select it.
    Note: (Windows® only) If you want to select fonts from the Windows directory, for example, WINNT or WINDOWS, you must retype the name of the TTF or TTC file in the Open window, which is shown here:
    Open window in WINNT directory
    By default, if you double-click the file in the WINNT directory, Windows opens the TTF or TTC file instead of selecting it, so to make a selection, you need to type the name. To use the mouse for this selection, copy the TTF or TTC file to another directory. Then, you will be able to use the mouse to click and select the font file.

    If a TTC file is selected, a valid font name must be entered.

    Select Create CID-keyed font metrics for fonts with large character sets, such as for Chinese, Japanese, and Korean language fonts.

  6. Click OK in the Documentation Font window to complete the selection. You should see the new font in the Manage Documentation Fonts window.
    Note: In the Documentation Generation wizard, names of registered fonts, including double-byte character set font names, are displayed only in Latin letters.
  7. Click OK to go back to the Documentation Style Settings page where you can now select the new font for the listed types of text.

The new font is now registered, which makes it available for all subsequent documentation generations. Default fonts cannot be removed.

Related reference
Documentation of resources

Feedback
(C) Copyright IBM Corporation 2005, 2006. All Rights Reserved.