Step 6: Advanced configurationAs standard, AdeliaDoc applies default generation rules which may not always fit your requirements. That is why, on a project-by-project basis, you can modify AdeliaDoc's default behavior by overloading certain generation rules. That is the purpose of the "adeliadoc.ini" configuration file.
In this tutorial, we will focus on modifying index generation rules and excluding the *@author annotation. For a full overview of advanced configuration options, see the adeliadoc.ini configuration file help topic.
Editing the "adeliadoc.ini" file The configuration file is encoded in UTF-8 without BOM. Therefore, an appropriate editor needs to be used (Notepad++ for example)
Modifying index generation rules As standard, and in addition to indexes associated with *@index annotations added to 4GL sources, AdeliaDoc generates as many index entries as documented programs and procedures. Each index entry has the name of the corresponding entity. This behavior is not always suited to the different types of documentation and particularly in our test project where we decided to explicitly and exhaustively generate index entries via the *@index annotation. That is why we are going to modify the index_generation parameter by assigning the "annotation" value to tell AdeliaDoc not to generate the implicit index entries based on the section names: Pas de format |
---|
index_generation = annotation |
As you can see in the documentation, the available configuration makes it possible to fairly specifically configure the behavior relating to index generation.
Excluding *@author annotations In certain situations, it may be beneficial to not include information relating to certain annotations in the documentation, even if these are explicitly present in a 4GL source. For example, developers' names in public documentation. The exclude_annotations parameter is intended for this purpose. Simply assign the parameter the value as follows: Pas de format |
---|
exclude_annotations = *@author |
Note on regenerating documentation At this stage, we have simply modified the AdeliaDoc configuration file, without further modifications to 4GL sources since the last generation. The incremental AdeliaDoc build process must therefore inhibit documentation regeneration as there was no source modification. However, due to the fact that these configuration modifications have a direct impact on the content of information included in the documentation (new version of the index page and deletion of developers' names in our example), AdeliaDoc will be able to detect these parameter changes in order to switch to forced generation mode. More generally, AdeliaDoc disables incremental generation when all the context conditions are not met, based on a data cache associated with the documentation project.
An example Command for generating the sample documentation project generation command: Pas de format |
---|
c:\Test>adeliadoc -ACTION:generate -project:"c:\Test\AdeliaDocProject" -env:TEST_ENV -format:HTML -pgm:ADEL_DOC1;ADEL_DOC2 -log:c:\temp\adeliadoc.log |
If everything has gone well, the message "The operation completed successfullyOperation successful" is displayed in green on the screen: You will see warning messages displayed on the screen indicating that AdeliaDoc has forced full generation mode. In the regenerated documentation, the information relating to the section authors has disappeared. The index page no longer contains the entries corresponding to the inserted annotations.
If there is an error, the "The operation failed" message is displayed in red on the screen, with the explanatory error message. See the log file for more details.
Info |
---|
| With regard to incremental generation, note that you can at any time tell AdeliaDoc to force full regeneration of the documentation, avoiding incremental mode. To do this, simply use the force parameter when running the generation action. |
|