Principes

Alors qu'AdeliaDoc se charge de générer une collection de fichiers source au format reStructuredText (langage de markup orienté documentation) à partir de l'analyse des sources L4G annotés et de l'exploitation des informations de description des programmes Adélia, Sphinx, de son côté, traite et transforme cette collection pour produire une hiérarchie de pages d'aide qui vont constituer le support de documentation dans le format attendu (HTML, PDF, etc.).

A noter qu'AdeliaDoc encapsule et masque l'appel aux traitements Sphinx lors de l'exécution d'une action generate ou d'une action make. 

Pour que Sphinx puisse traiter correctement la collection de fichiers markup source, et produire selon les critères de mise en page voulus la documentation dans le format cible choisi, AdeliaDoc se charge également de créer, lors de l'initialisation d'un projet de documentation, deux fichiers paramètres complémentaires à destination de Sphinx : "index.rst" et "conf.py". Ces deux fichiers sont localisés dans le sous-répertoire "source" d'un projet de documentation.

Contrairement à la collection de fichiers markup source, qui évolue et qui est potentiellement modifiée à chaque fois que des programmes et/ou leurs dépendances sont modifiés, ces deux fichiers paramètres, après avoir été créés lors de l'initialisation d'un projet, ne sont par la suite plus jamais modifiés par AdeliaDoc. 

Pour autant, et dans le but de pouvoir personnaliser le support de documentation produit, les fichiers "index.rst" et "conf.py" créés avec un paramétrage standard peuvent parfaitement être modifiés et adaptés à vos besoins, selon des règles précises documentées sur le site de Sphinx.

Ces modifications sont conservées tout au long du cycle de vie d'un projet de documentation, y compris lors de l'exécution de l'action cleanup.

Avant d'entreprendre des modifications avancées au niveau de ces deux fichiers Sphinx, nous vous conseillons fortement de lire attentivement la documentation.

Néanmoins, pour vous aider dans cette démarche et vous permettre de personnaliser à minima la documentation produite, vous trouverez dans la suite de ce document des explications relatives au contenu de ces deux fichiers paramètres. 

Personnalisation de la page d'accueil de la documentation : fichier index.rst

Le contenu de ce fichier permet à la fois :

• de structurer et de personnaliser le contenu de la page d'accueil du support de documentation,
• de définir la manière dont la collection de fichiers markup source générés par AdeliaDoc est liée à une hiérarchie unique de pages d'aide, au travers de la directive Sphinx "toctree".

Par nature, ce fichier a vocation à être modifié de façon à vous permettre d'adapter et de personnaliser au mieux la page d'accueil du support de documentation. 

Vous devez cependant veillez à ce que ces modifications :

• respectent la syntaxe de markup reStructuredText et des directives Sphinx que vous souhaiteriez ajouter,
• n'aboutissent pas à la suppression de la directive Sphinx  toctree  qui, en faisant référence aux répertoires des fichiers markup source générés par AdeliaDoc, permet d'assembler la documentation finale.
  Ainsi, cette directive :
  • peut être placée à l'endroit qui vous convient dans le fichier,

  • mais doit à minima respecter le formalisme suivant :

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

  • tout en pouvant inclure l'option ":hidden:", qui permet de masquer la table des matières dans le support généré.

Modification de la configuration Sphinx : fichier conf.py

Ce fichier englobe un ensemble de paramètres de configuration permettant :

• de personnaliser le comportement de Sphinx dans sa façon de traiter les fichiers markup en entrée (générés par AdeliaDoc), et
• de construire le support de documentation en sortie.

Un nombre restreint de ces paramètres sont figés pour les besoins d'AdeliaDoc, et ne doivent en aucun cas être modifiés. Les autres sont libres de modifications, et peuvent de ce fait être ajoutés, modifiés ou supprimés en fonction de vos besoins.

La liste des paramètres imposés par AdeliaDoc est relativement limitée :

• templates_path : par défaut, AdeliaDoc crée le sous-répertoire "_templates" dans l'arborescence d'un projet de documentation.
  Ce paramètre contient donc par défaut ce sous-répertoire, qu'il est conseillé d'utiliser si vous souhaitez développer vos propres templates.
  Cependant, vous pouvez tout à fait ajouter vos propres répertoires à ce paramètre.
• html_static_path : par défaut, AdeliaDoc crée le sous-répertoire "_static" dans l'arborescence d'un projet de documentation.
  Ce paramètre contient donc par défaut ce sous-répertoire, qu'il est conseillé d'utiliser si vous souhaitez ajouter des ressources statiques (images, feuilles de style...) pour vos besoins de personnalisation.
  Cependant, vous pouvez tout à fait ajouter vos propres répertoires à ce paramètre.
• source_encoding : type d'encodage des fichiers markup source générées par AdeliaDoc.
  Fixé à "UTF-8".
• html_use_index : la valeur de ce paramètre, destiné à activer la présence d'une page index dans le cas d'une génération au format HTML, est pilotée par AdeliaDoc via le paramètre de configuration  index_generation .
  Les éventuelles modifications apportées à ce paramètres seraient donc écrasées par AdeliaDoc, et par conséquent perdues.

Les autres paramètres sont libres et peuvent faire l'objet de modifications, notamment afin :

• de modifier les intitulés et informations de description du projet, ces éléments étant incorporés dans la documentation produite ;
• de modifier le code langue, initialisé par AdeliaDoc lors de la création d'un projet, mais que vous pouvez éventuellement modifier par la suite ;
• d'intervenir sur les options spécifiques au format HTML, qui permettent principalement : 
  • de personnaliser le comportement et l'aspect des pages HTML générées,
  • de choisir le thème principal de présentation, via le paramètre "html_theme" (sachant qu'il est possible de créer son propre thème),
  • de modifier le look & feel du thème choisi, via le paramètre "html_theme_options", relié à un ensemble d'options à disposition.
• de personnaliser la production de la documentation aux formats Texte et LaText (PDF).