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:
- 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
- An app for testing ALDoc
- 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:
- Subfolder supporting
- 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.
Pingback: Generating help with the ALDoc tool | Pardaan.com
Nice blog, would love to see MS supporting subfolders as well instead of having to change our repo structures by moving away from a \src folder.
https://github.com/microsoft/AL/issues/7502
Hello Frederic,
Excellent! You’ve reported the issue on GitHub. During the BCLE session, I observed that ALDoc might utilize namespaces to create a more organized structure. I haven’t had a chance to test it yet, but I’ll provide an update as soon as possible. If the tests yield positive results, it could serve as a useful workaround. However, I’m not considering adopting namespaces in the near future, at least not until Microsoft fully incorporates them. Perhaps I’ll explore this further in a future blog post. ????