Before you start

If you have not already done so, it is a good idea to install all the third-party tools used by AdeliaDoc.

These tools need to be installed in order for the documentation generator to operate correctly.

In this tutorial, we are going to work on a documentation project:

• in English (project's standard language along with French),
• which will be located in the c:\Test\AdeliaDocProject directory,
• and will include two Visual Adelia batch programs ADEL_DOC1 (accompanied by the PROC1 procedure) and ADEL_DOC2, and an ADEL_CLASS1 class.

The two programs and the class have the sole aim of illustrating AdeliaDoc's features so will only contain the minimum code required to produce the documentation.

Below is the basic code for these three entities, which you can copy into your test environment.

All AdeliaDoc commands are passed from the Windows® command prompt (⊞ Win-r and enter "cmd").

If the Adelia Studio installation directory is not in the PATH environment variable of your Windows® session, go to the Adelia Studio directory ("C:\Program Files (x86)\Adelia Studio" by default) before running the AdeliaDoc commands.

Step 1: Initialize the documentation project

• configuration files initialized with the default values,
• the command files required to call Sphinx,
• as well as the different related resources.

• the directory where the project will be located (mandatory),
• a language code (mandatory), which will be the documentation language - the list of supported languages is the list of language codes offered by Sphinx,
• the documentation project title can also be passed as a parameter.
  This parameter is optional. We will see in the next step how to customize the documentation project by modifying the default title set by AdeliaDoc among other things.

An example documentation project initialization command:

c:\Test>adeliadoc -ACTION:init -lang:en -project:"c:\Test\AdeliaDocProject" -log:c:\temp\adeliadoc.log

• if everything has gone well, the message "Operation successful" is displayed in green on the screen:
  • The source markup files generated by AdeliaDoc from the 4GL program analysis will be produced in the "classes" and "programs" sub-directories of the "source" sub-directory.
  • the "build" sub-directory will contain the documentation built by Sphinx, based on the processing of source markup files.
• if there is an error, the message "The operation failed" is displayed in red on the screen, with the explanatory error message.

Step 2: Customize the project 

After initializing a project, it is usually best to modify the standard configuration in order to customize at least the content of the document's common constituent elements, and in particular, the main page (i.e. the home page for documentation in HTML format).

In this tutorial we suggest:

• modifying the titles in the source markup file corresponding to the main page: "index.rst" file;
• modifying the project's general information in the Sphinx configuration file: "conf.py" file.

To do that, you need to open these two files in an editor which supports UTF-8 encoding (Notepad++ for example), which is the encoding of all the files handled by AdeliaDoc. You need to make sure you save your changes in this encoding of course.

Modifying the "index.rst" file

• The aim is to change the project title by replacing the "Welcome to Adelia API documentation!" title with "My first AdeliaDoc documentation Project" for example.
  • This is a text type file but uses reStructuredText markup syntax to define the formatting.
  • This, along with the fact that the new title is longer than the default one, is why the line of "==" characters just below the new title needs to be lengthened.
    This line is used to display a section title in the page.
• Once the change has been made, save the file.
• This file can be customized further - see the home page customization help page for further details.

Modifying the "conf.py" file

• The aim is to change the project's general information, i.e. the project name and version:
  • For the project name, identify the "project" parameter and assign it the "My doc project" value instead of "Adelia API".
  • For the version, identify the "release" parameter and assign it the "2.0" value instead of "1.0".
• Once the change has been made, save the file.
• This file can of course be customized further - see the Sphinx configuration customization help page for more information.

Step 3: Generate default documentation in HTML format

Remember that AdeliaDoc is used to generate technical documentation associated with Adelia programs based on:

• the analysis of 4GL sources,
• the use of program description information,
• specific annotations in the form of comments which were added to the 4GL source by the developers.

• the directory where the project will be located (mandatory),
• the Adelia environment containing the sources - in this case, it is called "TEST_ENV",
• the desired format for the documentation (HTML in our case),
• as an option, you can restrict the list of programs to be included in the documentation, bearing in mind that by default, if nothing is specified, the generated documentation will include the whole repository of the environment passed as a parameter. In this case, as we simply want to create documentation including two programs, we will use the optional ad hoc parameter called pgm.

Command for generating the sample documentation project:

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 "Operation successful" is displayed in green on the screen:

  • You may receive warnings - ignore these for the purposes of this tutorial.

  • The main page of the generated documentation is "C:\Test\AdeliaDocProject\build\html\index.html"

  • The help sections relating to our two programs have been generated with default values, including the "PROC1" procedure of "ADEL_DOC1".

  • As one of the "ADEL_DOC1" program parameters references a class, the corresponding class is automatically generated by AdeliaDoc and a hypertext link provides direct access from the program's help page. You will notice that the *SER_DESC declarations positioned on the declaration and a class attribute have been included in the documentation.

  • Finally, you will also notice that the customizations performed in step 2 have been applied.

• 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.

Step 4: Add annotations to 4GL sources

Now we have the basic documentation, we will add annotations to the 4GL sources to self-document the programs.
The available annotations cover most technical documentation requirements.
We will only look at some of these in this tutorial. 

To insert annotations into the programs, you just need to copy the annotation code provided below before the PARAM instruction for the corresponding programs/procedures. In practice, it is of course possible to structure things differently, as long as the annotations are all before the PARAM instruction.

Adding annotations to the ADEL_DOC1 program

The modifications involve:

• for the program itself:
  • adding a program description annotation which includes the text formatting and a link to the ADEL_DOC2 program,
  • adding a description annotation for the list parameter named "LST" (and two of its fields) and for the "DT1" parameter,
  • adding an index annotation with two entries.
• for the PROC1 procedure:
  •  adding a deprecation annotation. 

Adding annotations to the ADEL_DOC2 program

The modification involves adding two hierarchy index annotations - one for which the parent has already been created (see ADEL_DOC1 ) and one for which it has not.

Step 5: Take into account added annotations

After saving the programs, restart the generation.

Command for generating the sample documentation project:

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 "Operation successful" is displayed in green on the screen and you will see that the inserted annotations appear in the new version of the documentation:

  • the ADEL_DOC1 program descriptions and parameters, with the formatting (bold) and hypertext links,

  • the deprecation comment on the procedure,

  • the index page with our different hierarchical or simple entries (see the next step for advanced use of the index page) of the ADEL_DOC2 program.

• 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.

Step 6: Advanced configuration

As 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: 

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: 

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.

Command for generating the sample documentation project:

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 "Operation 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.

Step 7: Generate the documentation in TEXT format

After regenerating the documentation in HTML format, you may wish to create your documentation in other supported formats, for example a purely text format.

In this case, and rather than restarting a complete generation process, it is easier and quicker to just restart a Sphinx build of the documentation in the new target format.

The make action is specifically suited to this situation: it involves only running documentation production via a call to Sphinx, based on the source markup files generated by AdeliaDoc.
This action requires the following to be passed as parameters:

• the directory where the project is located (mandatory),
• the desired format (mandatory).

Command for generating the sample documentation project:

c:\Test>adeliadoc -ACTION:make -project:"c:\Test\AdeliaDocProject" -format:TEXT -log:c:\temp\adeliadoc.log

• If everything has gone well, the message "Operation successful" is displayed in green on the screen. The generated text files are in "C:\Test\AdeliaDocProject\build\text".

• If there is an error, the "The operation failed" message is displayed in red on the screen, with the explanatory error message.