Generate help with the ALDoc tool

  • 6 minutes

To aid consuming apps downstream, documentation is a major benefit. Until now, it was a large manual process to create and keep that in sync with app changes, unless the publisher invested in automation themselves.

For extension publishers, we provide a new ALDoc tool.

The ALDoc tool generates documentation from symbolic and syntactical information, code comments, and overall application structure based on input .app files. You can use it to generate internally or externally facing reference documentation for your solution.

The tool also generates a help site with the reference articles, sorted by the application structure, based on the provided custom template.

Generating content based on source code has many advantages such as accuracy, 100% reflection of the current codebase, less error prone documentation, and it saves time. The ALDoc tool generates documentation from symbolic and syntactical information, code comments, and overall application structure based on input .app files. The tool also generates a help site with these reference articles, sorted by the application structure, based on the provided template.

This article describes the necessary steps to use the ALDoc tool to generate the documentation for AL .app packages. The ALDoc tool relies on the DocFx tool, and needs the DocFx prerequisites to be available on the machine that generates the reference documentation.

To generate help using the ALDoc tool, the following steps are involved:

  1. Install DocFx and .NET prerequisites

  2. Get the ALDoc tool from the .vsix file

  3. Generate the reference documentation files

  4. Build a static web site for the generated documentation

To use the ALDoc tool, you must have the following prerequisites installed on your machine.

Install the DocFx tool after you install .NET 6.0 or higher. DocFx is an open-source tool used to generate static sites. It's designed to create reference documentation based on .NET code and XML comments. The ALDoc tool adds support for generating documentation for AL objects with DocFx. For more information, see Basic concepts in DocFx.

Start a command line tool as administrator, and run the following command to install the .NET DocFx tool, version 2.70.0, the newest recommended version for 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

After the installation is complete, you have the latest version of the DocFx tool on your machine.

The ALDoc tool is shipped with the AL Language extension for Microsoft Dynamics 365 Business Central, and can be found in the equivalent location of:

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

When all prerequisites are successfully installed, the next step is to use the ALDoc tool to generate the documentation files. For this, you must have the .app files that you want to generate documentation for available on your machine. You also need to have a folder available where the generated files can be placed.

  1. First, initialize the reference repo by providing the following command. The initialization unpacks AL support files, and creates the input folder for the DocFx tool including the DocFx configuration file (docfx.json).

    • Command syntax

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

    • Example

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

  2. Next, generate the reference files for each .app file that you specified in the previous step. The build command must be run for each .app file that you want to generate documentation for. Furthermore, it's important for the cross references that the build command has access to the complete set of dependent .app files that you intend to generate documentation for. You specify these files with the -c parameter.

    • Command syntax

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

    • Example

      .\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 the next steps, you use the DocFx tool to build and host the static website.

In the previous steps, the initialization and reference files were generated. You can now use DocFx to build a website to host the generated files, which you can share with your users internally and or externally.

  1. In the command line, enter a command equivalent to this one:

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

  2. Next, to host the website locally, enter a command equivalent to this one:

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

  3. Then wait for the build to complete and in a browser window, type https://localhost:8080 to check the generated website. You should now see the table of contents to the left, and the generated articles to the right.

For more information about getting started with the DocFx tool, see Quick start.

Some areas of autogenerated content work as they are, giving information about syntax, showing any code comments, and displaying the overall application structure. But some areas of the autogenerated content might need more information, guidance, or remarks to add value. The ALDoc tool supports overwrites of the autogenerated articles. An overwrite file contains content that is injected into autogenerated content and it doesn't overwrite autogenerated content. For more information, see Overwriting help with the ALDoc tool.