Documentation Generation

Documentation Generation

Overview

Choose Documentation Template

Documentation Generator Status Dialog

Organizing Project Documentation

Overview

All you need to do to generate documentation is to start the Documentation > Generate Documentation command and select one or more DTs in which documentation attributes are specified

Choose Documentation Template

You can select a DT in several ways, depending on the option selected in the generate group (Generate Tab). The quickest way is to find one of the recently used DTs on the Recent list. This dialog at first offers a list of often used DTs:

active () - Active DT in DTE, i.e. the one which has focus.

opened () - DTs which are not active but are open in DTE.

recent () - DTs which are not open in DTE but have recently been used.

standard () - DTs which reside in the standard documentation template directory (Options/Documentation/Directories/Standard Documentation Templates)

additional ()- DTs which were not offered at first, but which can be selected via the Browse button.

A larger number of DTs can be selected in the dialog, and generation will be started on the basis of the selected DTs.

Documentation Generator Status Dialog

After this, until the documentation generation process is completed, you can follow the generation via the Generate Documentation status dialog shown on the following image:

Before the documentation generation starts, the SCA database will be updated if the Update database before generating option has been selected in the Generating tab of the Documentation Generator Options dialog box. Before documentation is generated, the serviceability of all selected DTs is assessed. Only if all the DTs are serviceable (there are no errors, warnings there can be), documentation generation is started.

During generation, in the "The Documentation Status dialog" you get information on which DT is currently being processed, how many warnings and errors have been found so far. You can stop the generation any time by clicking Cancel.

Once the generation has been completed, in the "The Documentation Status dialog" information on the number of errors, number of DTs assessed, and number of documents generated is displayed.

If there were no errors in the DTs (warnings can be present) and the generation process itself passed without errors, then all GDs will be opened in DTE. If there are any warnings, the DA-C Messages window will appear.

If the generation was stopped due to errors in the DTs, the Messages window will also appear. By double-clicking the warning or error in the Messages window, you can position the insertion point on the exact point where the error or warning occurs in DT. If a run-time error appears, the generation process is stopped, and the error message displayed in a separate Message box.

During DT specification, you will often need to assess the serviceability of DT content, especially if you do not use the Wizard when integrating DGML scripts. As you have seen in the previous chapter, serviceability assessment always precedes documentation generation but in situations when you do not want to generate documentation but only to assess the DT you are working on, the quicker way is to start DT serviceability assessment (the Documentation/Check Template template). Only a syntactic and semantic check is preformed in this way, and run-time errors cannot be detected.

After starting the Documentation/Check Template command, you need to select one or more DTs from the "The Generate dialog"; otherwise the DT set in the configuration is checked. You can specify whether all DTs nested (included) in the selected DTs will also be checked.

As with generating, in the "The Documentation Status dialog" you get information on the number of errors, number of warnings, and number of DTs assessed.

When the serviceability assessment has been completed, "All templates are checked" appears on the status bar. Clicking the OK button closes the dialog and the Messages window appears with the Documentation tab active. In the Messages window, all the errors and warnings in the assessed DTs are displayed. By double-clicking a warning or an error in the Messages window you can position the insertion point at the exact point where the error or warning occurs in DT.

Organizing Project Documentation

Good documentation template and generated documentation organization can make generating documentation and finding generated documents easier and more efficient. Apart from the already familiar way of adding files to logical groups it is possible include any newly created or open DT in the logical group Default(types) / Document Files / Templates (option), as well as to include any GD in the logical group Default(types)/Document Files / Generated documents after generation.

In the Directories tab in the configuration you can specify the path to the folder where your DT's, i.e. you GD's are located. In this way, DTs are added to the logical group Default(types)/Document Files /Templates and GD's are added to the logical group Default(types)/Document Files /Generated documents.