Products Downloads


French version


 

General

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

  1. The initialization of a documentation project, configured with the default parameters.
  2. The generation of source markup files (.rst) from the analysis of 4GL sources and the use of program description information.
  3. Documentation production in the required format from the source markup files.
  4. The deletion of all the elements from the generation, keeping customized configuration parameters as well as the Sphinx configuration.
  5. 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
NameDescriptionMandatory
action

Action to execute: init|generate|make|cleanup|delete

yes
project

Documentation project's root directory

yes
envAdelia generation environmentno(1)
app_area

Name of application area(s) concerned by the generation

no
build_compName of build component(s) concerned by the generationno
pgm

Name of program(s) concerned by the generation

no
filterFilter based on the presence and content of the *@adeliadoc annotation, used to separate some programs/procedures from the generationno
formatDesired format for the documentationyes(3)
langDocumentation project's language codeno(2)
titleDocumentation project titleno
forceForced mode for full documentation generation, avoiding incremental mode
no
logLog file absolute pathno

(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 parameterslang, project
Optional parameterslog, title
NoteAfter 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.
Exampleadeliadoc  - 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 parameterproject
Optional parameterlog
Exampleadeliadoc  - action:cleanup -project:"d:\adeliaDoc\bdcadel\public"




  • generate: generation of pivot files and documentation building
Mandatory parametersproject, env, format
Optional parametersapp_areapgmbuild_comp, filter,force, log
Notes
    • If none of the optional parameters app_areabuild_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.
Exampleadeliadoc  - action: generate  - env:bdcadel @hostame -project:"d:\adeliaDoc\bdcadel\public"
- format:html  -a pp_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 parametersproject, format
Optional parameterlog
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.
Exampleadeliadoc  - action:make   -project:"d:\adeliaDoc\bdcadel\public" - format:pdf



  • delete: permanent deletion of a documentation project
Mandatory parameterproject
Optional parameterlog
NoteThe content of the directory associated with the documentation project and the directory itself are deleted.
Exampleadeliadoc  - 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

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

DescriptionCanonical name of the Adelia generation environment
ValueName 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 -a pp_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

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

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

- project:"d:\adeliaDoc\bdcadel\public" - format:html
-log:"c:\temp\adeliadoc_project_bdcadel_public_logfile.log"

  • when used with a default value: 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


  • Aucune étiquette