Principles

While AdeliaDoc generates a collection of source files in reStructuredText format (documentation-oriented markup language) based on the annotated 4GL source analysis and the use of Adelia program description information, Sphinx, on the other hand, processes and transforms this collection to produce a hierarchy of help pages which will create the documentation in the required format (HTML, PDF, etc.).

Note that AdeliaDoc encapsulates and masks the call for Sphinx processing when executing a generate or make action. 

To enable Sphinx to process the collection of source markup files correctly and produce the documentation in the chosen target format according to the required layout criteria, AdeliaDoc also creates two additional parameter files for Sphinx when initializing a documentation project: "index.rst" and "conf.py". These two files are located in the "source" sub-directory of a documentation project.

Unlike the collection of source markup files, which changes and may potentially be modified each time the programs and/or their dependencies are changed, once they have been created during project initialization, these two parameter files are never subsequently modified by AdeliaDoc. 

However, in order to be able to customize the produced documentation, the "index.rst" and "conf.py" files created with a standard configuration can be modified and adapted to your needs according to specific rules detailed on the Sphinx website.

These changes are kept throughout a documentation project's life cycle, including during the execution of the cleanup action.

Before making advanced changes in these two Sphinx files, we strongly advise reading the documentation carefully.

Nevertheless, to help you with this process and enable you to make at least some customizations to the produced documentation, this document contains information about the content of these two parameter files. 

Customizing the documentation home page: index.rst file

The content of this file enables you to:

• structure and customize the content of the documentation home page,
• define the way in which the collection of source markup files generated by AdeliaDoc is linked to a single hierarchy of help pages, using the Sphinx "toctree" directive.

By its nature, this file is intended to be modified so you can adapt and customize the documentation home page. 

You must, however, ensure that these changes:

• comply with the reStructuredText markup syntax and that of the Sphinx directives you wish to add,
• do not result in deleting the Sphinx toctree directive which, by referring to the source markup file directories generated by AdeliaDoc, enables the final documentation to be assembled.
  Therefore, this directive:
  • can be placed wherever you like in the file,

  • but must at least comply with the following form:

    .. toctree:: :glob: programs/* classes/*

  • and may include the ":hidden:" option which is used to hide the table of contents in the generated document.

Changing the Sphinx configuration: conf.py file

This file includes a set of configuration parameters enabling you to:

• customize the way Sphinx processes input markup files (generated by AdeliaDoc), and
• build the output documentation.

A small number of these parameters are fixed to meet AdeliaDoc's requirements and must not be changed in any circumstances. The others can be changed and therefore added, changed or deleted according to your requirements.

There are relatively few parameters imposed by AdeliaDoc:

• templates_path : by default, AdeliaDoc creates the "_templates" sub-directory in a documentation project's tree view.
  This parameter therefore contains this sub-directory by default. We recommend using this sub-directory if you wish to develop your own templates.
  However, you can add your own directories to this parameter.
• html_static_path : by default, AdeliaDoc creates the "_static" sub-directory in a documentation project's tree view.
  This parameter therefore contains this sub-directory by default. We recommend using this sub-directory if you wish to add static resources (images, style sheets, etc.).
  However, you can add your own directories to this parameter.
• source_encoding : encoding type for source markup files generated by AdeliaDoc.
  Set to "UTF-8".
• html_use_index : the value of this parameter, intended to enable the presence of an index page in the case of generation in HTML format, is managed by AdeliaDoc via the index_generation configuration parameter.
  Any changes to these parameters will therefore be overwritten by AdeliaDoc and lost.

The other parameters are free and can be modified, particularly in order to:

• change the project description titles and information as these elements are incorporated into the produced documentation;
• change the language code initialized by AdeliaDoc when creating a project, but which you can subsequently change;
• change the specific HTML format options, which mainly enable you to: 
  • customize the behavior and appearance of the generated HTML pages,
  • choose the main presentation theme via the "html_theme" parameter (bearing in mind that you can create your own theme),
  • change the look & feel of the chosen theme via the "html_theme_options" parameter, linked to a set of available options.
• customize documentation production in Text and LaText (PDF) formats.