Hilfe mit dem ALDoc-Tool generieren

  • 6 Minuten

Die Dokumentation ist sehr vorteilhaft, um bei der nachgelagerten Nutzung von Apps zu helfen. Es stellte bisher einen umfassenden manuellen Prozess dar, die App zu erstellen und mit Änderungen an der App zu synchronisieren, es sei denn, der Herausgeber investierte selbst in die Automatisierung.

Wir stellen für Herausgeber von Erweiterungen ein neues ALDoc-Tool bereit.

Das ALDoc-Tool generiert Dokumentation aus symbolischen und syntaktischen Informationen, Codekommentaren und der gesamten Anwendungsstruktur auf Basis von eingegebenen .app-Dateien. Damit können Sie eine Referenzdokumentation zu Ihrer Lösung für interne oder externe Zwecke erstellen.

Das Tool generiert zudem basierend auf der bereitgestellten benutzerdefinierten Vorlage eine Hilfeseite mit den Referenzartikeln, sortiert nach der Anwendungsstruktur.

Das Generieren von Inhalten auf Basis des Quellcodes bietet viele Vorteile wie Genauigkeit, 100-%ige Wiedergabe der aktuellen Codebasis, weniger fehleranfällige Dokumentation und Zeitersparnis. Das ALDoc-Tool generiert Dokumentation aus symbolischen und syntaktischen Informationen, Codekommentaren und der gesamten Anwendungsstruktur auf Basis von eingegebenen .app-Dateien. Das Tool generiert zudem basierend auf der bereitgestellten Vorlage eine Hilfeseite mit den Referenzartikeln, sortiert nach der Anwendungsstruktur.

In diesem Artikel werden die notwendigen Schritte beschrieben, mit denen Sie mit dem ALDoc-Tool die Dokumentation für AL .app-Pakete generieren können. Das ALDoc-Tool basiert auf dem DocFx-Tool, und die DocFx-Voraussetzungen müssen auf dem Computer verfügbar sein, auf dem die Referenzdokumentation generiert wird.

Die folgenden Schritte sind nötig, um mit dem ALDoc-Tool Hilfe zu generieren:

  1. DocFx‑ und .NET-Voraussetzungen installieren

  2. Das ALDoc-Tool aus der .vsix-Datei abrufen

  3. Die Referenzdokumentationsdateien generieren

  4. Eine statische Website für die generierte Dokumentation erstellen

Die folgenden Voraussetzungen müssen auf Ihrem Computer installiert sein, um das ALDoc-Tool verwenden zu können.

Installieren Sie das DocFx-Tool, nachdem Sie .NET 6.0 oder höher installiert haben. DocFx ist ein Open-Source-Tool zum Generieren statischer Websites. Dies wurde entwickelt, um Referenzdokumentation basierend auf .NET-Code und XML-Kommentaren zu erstellen. Das ALDoc-Tool bietet Unterstützung für die Erstellung von Dokumentation für AL-Objekte mit DocFx. Weitere Informationen finden Sie unter Grundlegende Konzepte in DocFx.

Starten Sie ein Befehlszeilentool als Administrator, und führen Sie den folgenden Befehl aus, um das .NET DocFx-Tool, Version 2.70.0, die neueste empfohlene Version für ALDoc, zu installieren.

# 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

Nachdem Sie die Installation erfolgreich abgeschlossen haben, befindet sich das DocFx-Tool in der neuesten Version auf Ihrem Computer.

Das ALDoc-Tool wird mit der AL-Spracherweiterung für Microsoft Dynamics 365 Business Central ausgeliefert und kann an entsprechender Stelle gefunden werden:

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

Wenn alle Voraussetzungen erfolgreich installiert sind, ist der nächste Schritt, das ALDoc-Tool zum Generieren der Dokumentationsdateien zu verwenden. Dazu müssen die .app-Dateien, für die Sie eine Dokumentation erstellen möchten, auf Ihrem Computer zur Verfügung stehen. Es muss zudem ein Ordner verfügbar sein, in dem die erstellten Dateien gespeichert werden können.

  1. Stellen Sie den folgenden Befehl bereit, um zunächst das Referenz-Repository zu initialisieren. Die Initialisierung entpackt AL-Unterstützungsdateien und erstellt den Eingabeordner für das DocFx-Tool mit der DocFx-Konfigurationsdatei (docfx.json).

    • Befehlssyntax

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

    • Beispiel

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

  2. Generieren Sie als Nächstes die Referenzdateien für jede .app-Datei, die Sie im vorherigen Schritt definiert haben. Der Erstellungsbefehl muss für jede .app-Datei ausgeführt werden, für die Sie eine Dokumentation erstellen möchten. Zudem ist es wichtig für die Querverweise, dass der Erstellungsbefehl Zugriff auf den vollständigen Satz abhängiger .app-Dateien hat, für die Sie Dokumentation generieren möchten. Sie geben diese Dateien mit dem -c-Parameter an.

    • Befehlssyntax

      {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}

    • Beispiel

      .\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'

In den nächsten Schritten verwenden Sie das DocFx-Tool zum Erstellen und Hosten von der statischen Website.

In den vorherigen Schritten wurden die Initialisierungs‑ und Referenzdateien erstellt. Sie können DocFx jetzt verwenden, um eine Website zu erstellen, auf der die erstellten Dateien gehostet werden, die Sie intern und/oder extern mit Ihren Benutzern teilen können.

  1. Geben Sie in der Befehlszeile einen Befehl ein, der folgendem entspricht:

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

  2. Geben Sie als Nächstes einen Befehl ein, der dem folgenden entspricht, um die Website lokal zu hosten:

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

  3. Warten Sie dann, bis die Erstellung abgeschlossen ist, und geben Sie https://localhost:8080 in ein Browserfenster ein, um die generierte Website zu überprüfen. Sie sollten nun links das Inhaltsverzeichnis und rechts die erstellten Artikel sehen.

Unter Schnellstart finden Sie weitere Informationen zu den ersten Schritten mit dem DocFx-Tool.

Einige Bereiche automatisch generierter Inhalte funktionieren unverändert und geben Informationen zur Syntax sowie etwaige Codekommentare und die gesamte Anwendungsstruktur an. Für einige Bereiche des automatisch generierten Inhalts werden jedoch möglicherweise weitere Informationen, Anleitungen oder Anmerkungen benötigt, um einen Mehrwert zu schaffen. Das ALDoc-Tool unterstützt Überschreibungen von den automatisch generierten Artikeln. Eine Überschreibdatei umfasst Inhalt, der in automatisch generierten Inhalt eingefügt wird, und überschreibt keinen automatisch generierten Inhalt. Unter Hilfe zum Überschreiben mit dem ALDoc-Tool finden Sie dazu weitere Informationen.