Générer de l’aide avec l’outil ALDoc

  • 6 minutes

Pour faciliter l’utilisation des applications en aval, la documentation constitue un avantage majeur. Jusqu’à présent, il s’agissait d’un vaste processus manuel permettant de créer et maintenir cela en phase avec les modifications d’application, à moins que l’éditeur n’investisse lui-même dans l’automatisation.

Pour les éditeurs d’extensions, nous proposons un nouvel outil ALDoc.

L’outil ALDoc génère une documentation à partir d’informations symboliques et syntaxiques, de commentaires de code et de la structure d’application globale basée sur les fichiers .app d’entrée. Il vous permet de générer une documentation de référence interne ou externe pour votre solution.

L’outil génère également un site d’aide avec les articles de référence, triés par structure d’application, sur la base du modèle personnalisé fourni.

La génération de contenu basé sur le code source présente de nombreux avantages tels que la précision, le reflet intégral de la base de code actuelle, une documentation moins sujette aux erreurs et un gain de temps. L’outil ALDoc génère une documentation à partir d’informations symboliques et syntaxiques, de commentaires de code et de la structure d’application globale basée sur les fichiers .app d’entrée. L’outil génère également un site d’aide avec ces articles de référence, triés par structure d’application, sur la base du modèle fourni.

Cet article décrit les étapes nécessaires pour générer la documentation pour les packages AL .app à l’aide de l’outil ALDoc. L’outil ALDoc s’appuie sur l’outil DocFx et a besoin des prérequis DocFx pour être disponible sur la machine qui génère la documentation de référence.

Voici les étapes permettant de générer de l’aide grâce à l’outil ALDoc :

  1. Installer les prérequis DocFx et .NET

  2. Obtenir l’outil ALDoc à partir du fichier .vsix

  3. Générer les fichiers de documentation de référence

  4. Créer un site web statique pour la documentation générée

Pour utiliser l’outil ALDoc, vous devez disposer des prérequis suivants installés sur votre machine :

Installez l’outil DocFx après avoir installé .NET version 6.0 ou ultérieure. DocFx est un outil open source permettant de générer des sites statiques. Il est conçu pour créer une documentation de référence basée sur du code .NET et des commentaires XML. L’outil ALDoc ajoute la prise en charge de la génération de documentation pour les objets AL avec DocFx. Pour en savoir plus, consultez Concepts de base dans DocFx.

Démarrez un outil de ligne de commande en tant qu’administrateur et exécutez la commande suivante pour installer l’outil .NET DocFx, version 2.70.0, la dernière version recommandée pour ALDoc :

# check nuget source is correct
dotnet nuget list source

# if list is empty, add nuget source
dotnet nuget add source --name nuget.org https://api.nuget.org/v3/index.json

# download and install docfx
dotnet tool install docfx --version 2.70 -g

Une fois l’installation terminée, vous disposez de la dernière version de l’outil DocFx sur votre machine.

L’outil ALDoc est livré avec l’extension AL Language pour Microsoft Dynamics 365 Business Central et peut être trouvé à l’emplacement équivalent du suivant :

C:\Users\<user>\.vscode\extensions\ms-dynamics-smb.al-12.0.836604\bin\win32\aldoc.exe

Une fois tous les prérequis installés avec succès, l’étape suivante consiste à générer les fichiers de documentation à l’aide de l’outil ALDoc. Pour ce faire, vous devez disposer des fichiers .app pour lesquels vous souhaitez générer de la documentation sur votre machine. Vous devez également disposer d’un dossier dans lequel les fichiers générés peuvent être placés.

  1. Tout d’abord, initialisez le référentiel de référence en fournissant la commande suivante. L’initialisation décompresse les fichiers de support AL et crée le dossier d’entrée pour l’outil DocFx, y compris le fichier config DocFx (docfx.json).

    • Syntaxe de la commande

      {path_to_aldoc}\aldoc.exe init -o .\{path-to-generated-content}\ -t '{path_to_package1}','{path_to_package2}',...,'{path_to_package3}'

    • Exemple

      .\aldoc\aldoc.exe init -o .mypath -t 'F:\AL\.alpackages\Microsoft_System Application_23.0.00000.0.app'

  2. Ensuite, générez les fichiers de référence pour chaque fichier .app que vous avez spécifié à l’étape précédente. La commande build doit être exécutée pour chaque fichier .app pour lequel vous souhaitez générer de la documentation. De plus, il est important pour les références croisées que la commande build ait accès à l’ensemble complet des fichiers .app dépendants pour lesquels vous avez l’intention de générer de la documentation. Vous spécifiez ces fichiers avec le paramètre -c.

    • Syntaxe de la commande

      {path_to_aldoc}\aldoc.exe build -o .\{path-to-generated-content}\ -c '{path_to_package_cache1}','{path_to_package_cache2}',...,'{path_to_package_cache3}' -s {path_to_package}

    • Exemple

      .\aldoc\aldoc.exe build -o .\mypath\ -c 'c:\my_path_package_cache1','c:\my_path_package_cache2','c:\my_path_package_cache3' -s 'F:\AL\.alpackages\Microsoft_System Application_23.0.00000.0.app'

Aux étapes suivantes, vous allez créer et héberger le site web statique à l’aide de l’outil DocFx.

Aux étapes précédentes, les fichiers d’initialisation et de référence ont été générés. Désormais, à l’aide de DocFx, vous pouvez créer un site web afin d’héberger les fichiers générés, que vous pouvez partager avec vos utilisateurs en interne et/ou en externe.

  1. Sur la ligne de commande, saisissez une commande équivalente à celle-ci :

    docfx build ./{path-to-generated-content}/docfx.json

  2. Ensuite, pour héberger le site localement, saisissez une commande équivalente à celle-ci :

    docfx serve ./{path-to-generated-content}/_site

  3. Attendez ensuite la fin de la build, puis tapez https://localhost:8080 dans une fenêtre de navigateur pour consulter le site web généré. Vous devriez maintenant voir le sommaire à gauche et les articles générés à droite.

Pour en savoir plus sur la prise en main de l’outil DocFx, consultez Démarrage rapide.

Certaines zones de contenu généré automatiquement fonctionnent telles quelles, donnant des informations sur la syntaxe et affichant des commentaires de code et la structure d’application globale. Mais certaines zones du contenu généré automatiquement peuvent nécessiter plus d’informations, de conseils ou de remarques pour ajouter de la valeur. L’outil ALDoc prend en charge les remplacements des articles générés automatiquement. Un fichier de remplacement comporte du contenu injecté dans du contenu généré automatiquement et ne remplace pas le contenu généré automatiquement. Pour en savoir plus, consultez Aide sur le remplacement avec l’outil ALDoc.