General

The AdeliaDoc tool is used to manage the whole life cycle of an Adelia technical documentation project, namely:

The initialization of a documentation project, configured with the default parameters.
The generation of source markup files (.rst) from the analysis of 4GL sources and the use of program description information.
Documentation production in the required format from the source markup files.
The deletion of all the elements from the generation, keeping customized configuration parameters as well as the Sphinx configuration.
The deletion of a documentation project.

In this context, the AdeliaDoc call parameters are based on a primary parameter called action, which triggers the execution of one of the life cycle phases described above.

Associated with this primary parameter is a set of secondary parameters (mandatory or optional) which are used to manage the actions in question. Some of these secondary parameters are common to all the actions.

Usage : adeliadoc -action:<ActionName> -project:<DirectoryName> -lang:<LanguageCode> -env:<EnvironmentCode> [-pgm:<ProgramsList> | -app_area:<ApplicationAreaList> | -build_comp:<ComponentList>]
        -format:<FormatCode> [-filter:<FilterList>] [-title:<ProjectTitle>] [-log[:<FileName>]] [-force]

Parameter description table

Preliminary comments:

The parameter input syntax is: -parameter[:value]
If a parameter value can include several occurrences, the occurrences must be separated by a semi-colon
For parameters with a value which may contain blanks, this must be in quotes: -param:"c:\temp\log file.txt"
The parameters and their values are not case sensitive

Name	Description	Mandatory
`action`	Action to execute: `init\|generate\|make\|cleanup\|delete`	yes
`project`	Documentation project's root directory	yes
`env`	Adelia generation environment	no⁽¹⁾
`app_area`	Name of application area(s) concerned by the generation	no
`build_comp`	Name of build component(s) concerned by the generation	no
`pgm`	Name of program(s) concerned by the generation	no
`filter`	Filter based on the presence and content of the `*@adeliadoc` annotation, used to separate some programs/procedures from the generation	no
`format`	Desired format for the documentation	yes⁽³⁾
`lang`	Documentation project's language code	no⁽²⁾
`title`	Documentation project title	no
`force`	Forced mode for full documentation generation, avoiding incremental mode	no
`log`	Log file absolute path	no

(1) except for the generate action

(2) except for the init action

(3) except for init|cleanup|delete actions

↑ Top of page

Detailed description of parameters

Below is a detailed description of all the call parameters supported by AdeliaDoc.

action parameter

Description

Code of the action to execute

Mandatory

Yes

Values

Take one of the following values:

init: documentation project initialization, in the specified directory (project parameter), for the specified language code (lang parameter).
The aim of initialization is to create the documentation project tree view, generate the default configuration files, the command files required to call Sphinx and the different associated resources.

Mandatory parameters	`lang`, `project`
Optional parameters	`log`, `title`
Note	After creating the project, the Sphinx configuration files and the AdeliaDoc configuration file can be customized to take into account the specific characteristics of the project.
Example	`adeliadoc -action:init -lang:en -project:"d:\adeliaDoc\bdcadel\public"` `-title :"API Documentation V1"`

cleanup: deletion of all files generated by AdeliaDoc in a project (including html and pdf files).
The Sphinx and AdeliaDoc configuration files containing the parameter customizations are retained.

Mandatory parameter	`project`
Optional parameter	`log`
Example	`adeliadoc -action:cleanup -project:"d:\adeliaDoc\bdcadel\public"`

generate: generation of pivot files and documentation building

Mandatory parameters	`project`, `env`, `format`
Optional parameters	`app_area`, `pgm`, `build_comp`, `filter`, `force`, `log`
Notes	If none of the optional parameters `app_area`, `build_comp`, `pgm` is present, the generation involves the whole repository. For each build, the make action is executed automatically following the pivot file generation. If conditions allow, generation is performed incrementally. This means that only the source markup files for which the corresponding programs (and/or their dependencies) have been modified since the previous generation are regenerated.
Example	`adeliadoc -action: generate -env:bdcadel @hostame -project:"d:\adeliaDoc\bdcadel\public"` `-format:html -app_area:STOCK -filter:public;core`

make: starts documentation production only, based on markup files (.rst) present in the "source" sub-directory of the specified project (files generated during a previous call to AdeliaDoc, with the action parameter set to generate).
This action can be useful in certain situations (changes to Sphinx appearance themes, production of documentation in another format based on the same collection of markup files, etc.).

Mandatory parameters	`project`, `format`
Optional parameter	log
Note	This action does not take into account any changes made to AdeliaDoc configuration parameters. Following such a change, a full generation must be initiated (generate action). Like for the generate action, make is an incremental process. Sphinx only regenerates documentation fragments for which the source markup files have been changed since the last generation.
Example	`adeliadoc -action:make -project:"d:\adeliaDoc\bdcadel\public" -format:pdf`

delete: permanent deletion of a documentation project

Mandatory parameter	`project`
Optional parameter	`log`
Note	The content of the directory associated with the documentation project and the directory itself are deleted.
Example	`adeliadoc -action:delete -project:"d:\adeliaDoc\bdcadel\public"`

project parameter

Description	Root directory of the documentation project (local directory on the machine running AdeliaDoc)
Value	Directory name
Actions	init: Mandatory generate: Mandatory make: Mandatory cleanup: Mandatory delete : Mandatory
Note	Make sure that the Windows® user running AdeliaDoc has read, write and delete permissions for the project directory.
Example	`adeliadoc -action:make -env:bdcadel @prodsrv -project:"d:\adeliaDoc\bdcadel\public" -format:htm`

env parameter

Description	Canonical name of the Adelia generation environment
Value	Name in question
Action	generate: Mandatory
Example	`adeliadoc -action:generate -env:bdcadel @prodsrv -project:"d:\adeliaDoc\bdcadel\public" -format:html`

App_area parameter

Description	Adelia environment application area(s) concerned by documentation generation
Values	List of application area names separated by the "`;`" character
Action	generate: Optional
Note	Exclusive with parameters `build_comp` and `pgm`
Example	`adeliadoc -action:generate -env:bdcadel @hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html -app_area:STOCK`

Build_comp parameter

Description	Adelia environment build component(s) concerned by documentation generation
Values	List of build components separated by the "`;`" character
Action	generate: Optional
Note	Exclusive with parameters `app_area` and `pgm`
Example	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html` `-build_comp:comp1;comp3`

Pgm parameter

Description	Adelia environment program(s) concerned by documentation generation
Values	List of program names separated by the "`;`" character
Action	generate: Optional
Note	Exclusive with parameters `app_area` and `build_comp`
Example	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html` `-pgm:programA;programC;programG`

Filter parameter

description	Filter based on the presence and content of the `*@adeliadoc` annotation, used to exclude certain sections (i.e. programs/procedures) from documentation generation. If the parameter is not entered, all the sections of the eligible program list are generated.
Values	Two predefined values are available: ALL: all sections containing an `@adeliadoc` (with or without label) are eligible. NONE: all sections containing an empty `@adeliadoc` (i.e. without label) are eligible. Or free content based on a list of labels separated by the "`;`" character: in this case, only sections with an `@adeliadoc` with the mentioned labels are eligible (NB: the `@adeliadoc` annotation in a program section is inherited by default by all its public procedures for which the annotation has not been entered).
Action	generate: Optional
Notes	The ALL and NONE values are exclusive. By its nature, the *ALL value cannot be accompanied by any other filter. A default filter can be configured in a project's configuration parameters. The default filter applies when this start parameter is not entered.
Example	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html` `-filter:public;core;*NONE`

Format parameter

Description	Desired format for the documentation
Values	HTML: documentation in HTML format PDF: PDF document LATEX: files in Latex format TEXT: files in plain text format RST: pivot files in reStructuredText markup format (`.rst`)
Actions	Generate: Mandatory make: Mandatory
Note	If the format is set to the RST value, AdeliaDoc generation is limited to markup file production without documentation production.
Example	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:pdf`

Lang parameter

Description	Documentation generation language
Value	AdeliaDoc supports all languages supported by Sphinx. The list of languages is available here.
Action	init: Mandatory
Note	It is always possible to change the language of a documentation project after creating it. For further information, see the help topic dedicated to localization.
Example	`adeliadoc -action:init -project:"d:\adeliaDoc\bdcadel\public" -lang:fr`

Title parameter

Description	Documentation project title
Value	Title in question
Action	init: optional
Note	The title of a documentation project can be changed after creating it. For further information, see the help topic on Sphinx customization and configuration.
Example	`adeliadoc -action:init -project:"d:\adeliaDoc\bdcadel\public" -title:"API Documentation V1" -lang:en`

force parameter

Description	Forced mode for full documentation generation, avoiding incremental mode
Value	None
Action	generate: optional
Note	When this parameter is set, the cleanup action is automatically called before the generate action is executed.
Example	`adeliadoc -action:generate -env:bdcadel@hostname -project:"d:\adeliaDoc\bdcadel\public" -format:html -force`

Log parameter

Description	Name of file containing the AdeliaDoc execution report
Value	Absolute file name If the file name is not entered, by default the report is created in the "`log`" sub-directory of the project (adeliadoc.log file). Important: for init and delete actions, you need to explicitly enter the absolute name of the report file.
Actions	Init: Optional generate: Optional make: Optional cleanup: Optional delete: Optional
Note	The generation report contains all the logs, messages (information/warning/error) and statistics relating to the execution of an AdeliaDoc action. In the case of the generate action, if this parameter is not entered, a default log is generated in case errors and/or warnings are raised during documentation generation. This default log is located in the "log" sub-directory of the project. For the other actions, all the messages are redirected to the standard output or error output (Windows® console by default).
Examples	for an explicit name for the log file: adeliadoc - action: generate - env:bdcadel `adeliadoc -action: generate -env:bdcadel -project:"d:\adeliaDoc\bdcadel\public" -format:html` `-log:"c:\temp\adeliadoc_bdcadel_public.log"` when used with a default value: adeliadoc - action: generate - env:bdcadel `adeliadoc -action:generate -env:bdcadel -project:"d:\adeliaDoc\bdcadel\public" -format:html -log`

↑ Top of page

AdeliaDoc return codes

The return codes returned by AdeliaDoc.exe can be classified into 3 categories:

Normal execution

- The execution was completed without errors or warning messages: the return code is therefore set to the "0" value.

Execution warnings

- If AdeliaDoc detects syntax errors in the annotations, or if differences are detected between the definition of parameters stored in the database in relation to the declaration of corresponding variables in the 4GL source, the return code is set to the "1" value.
  All the warning messages are recorded in the default log file or in the log file specified in the command line.
- If at least one of the programs or classes to generate does not pass the standard Adelia verification, the return code is set to the "2" value.
  All the warning messages are recorded in the default log file or in the log file specified in the command line.

Execution errors

- A return code with a value greater than "2" signifies that the requested action has not been completed.
  Additional information on the error type and reason is recorded in the standard output and in the log file.
- For information:
  - the "3" code indicates that standard Adelia verification has failed for all the eligible programs.
  - the "4" code indicates that there is no program to generate.
  - the "5" code indicates that the AdeliaDoc call parameters do not observe the required syntax rules.

↑ Top of page