Generating help with the ALDoc tool

When Microsoft initially introduced ALDoc, I was enthusiastic about testing it as soon as I could access the AL pre-release. However, my attempts to follow the official documentation resulted in disappointment as nothing worked as described.

I embarked on a quest to find more resources about ALDoc, but my efforts were met with limited success. Only Stefano Demiliani wrote an article titled Introducing ALDoc: a new command line tool for generating reference documentation for AL extensions. Although this article delves deeper than Microsoft's documentation, the outcome remained consistent: none of the instructions produced the desired results 😥

Determined to overcome these challenges, I chose to start anew and thoroughly analyze the issues at hand. In addition, I decided to write this post to provide assistance to those struggling with ALDoc.

To contribute my insights on this matter, I opted to follow the same Table of Contents as the official documentation for Generating help with the ALDoc tool. I will briefly outline the necessary adjustments.

Prerequisites

Ensure the installation of .NET SDK 6.0 or a higher version. The DocFx link can be disregarded.

Checking your .NET version

dotnet --list-sdks

The output should resemble the following:

DocFx

This is where you'll need to install DocFx.

Both the Microsoft documentation and Stefano's article suggest using the command:

dotnet tool update -g docfx

However, attempting this command will yield a result similar to:

The "update" aspect of this command might seem peculiar, as you can't update something that is not already installed. Fortunately, Microsoft updated the documentation after the release of a video by Erik Hougaard

dotnet tool install docfx --version 2.70 -g

If you give this a try, you might still encounter the same error:

In such a case, it's advisable to inspect your nuget source:

dotnet nuget list source

If the list is empty, you should add the source using the following command:

dotnet nuget add source --name nuget.org https://api.nuget.org/v3/index.json

Executing this command should successfully add the source:

With that completed, reattempt the following command:

dotnet tool install docfx --version 2.70 -g

The outcome should now be successful:

ALDoc

Now, you can proceed to follow the other steps outlined in the Microsoft documentation to experiment with ALDoc. Alternatively, you can continue reading or, even better, clone this repo and explore it yourself.

In my repository, I've included:

1. A script to facilitate DocFx installation. Feel free to comment out unnecessary lines

dotnet --list-sdks
dotnet nuget list source
dotnet nuget add source --name nuget.org https://api.nuget.org/v3/index.json
dotnet tool install docfx --version 2.70 -g

2. An app for testing ALDoc
3. A script for executing ALDoc

$app = '.\NavNab_AL Doc Example_1.0.0.0.app'
$aldoc = Resolve-Path "$($env:USERPROFILE)\.vscode*\extensions\ms-dynamics-smb.al-*\bin\win32\aldoc.exe" | Select-Object -ExpandProperty Path

$output = New-Item -ItemType Directory -Path ./output -Force
Remove-Item -Path "$output\*" -Recurse -Filter * -Force

. $aldoc init -o $output -t $app
. $aldoc build -o $output -c ./package -s $app

docfx build "$output/docfx.json"
docfx serve "$output/_site"

Based on my experimentation, I find ALDoc to be impressive. However, it still requires some improvements from Microsoft 🙈. For instance, if you're accustomed to having a "src" folder, you might need to reconsider that approach, as ALDoc struggles to manage subfolders.

Here are some functionalities I hope Microsoft incorporates into an upcoming version:

1. Subfolder supporting
2. Tooltips handling

Currently, I commend NAB AL Tools for providing similar tools a while ago. Nevertheless, I'm considering switching to ALDoc soon — my apologies to the NAB AL Tools team 🙈.

If you're still reading, I'd love to hear your feedback and to hear about the functionalities you wish to see in future versions. Feel free to share your thoughts in the comments below 😉.