ALDoc ツールを使用したヘルプの生成

  • 6 分

下流でのアプリの利用を支援する上で、ドキュメントは非常に有益です。 これまでは、公開元自身が自動化に投資していない限り、ドキュメントを作成してアプリの変更と同期させるのは大規模な手動プロセスでした。

拡張機能の公開元向けに、新しい ALDoc ツールが提供されています。

ALDoc ツールは、入力 .app ファイルに基づいて、記号や構文の情報、コードのコメント、およびアプリケーション構造全体からドキュメントを生成します。 これを使用して、ソリューションの社内または外部向け参照ドキュメントを生成できます。

このツールは、提供されたカスタム テンプレートに基づいて、参考記事がアプリケーション構造に従って並べられたヘルプ サイトも生成します。

ソース コードに基づいてコンテンツを生成すると、正確さが保たれる、現在のコードベースが 100% 反映される、ドキュメントの間違いが発生しにくくなるなどの多くの利点が得られ、時間も節約できます。 ALDoc ツールは、入力 .app ファイルに基づいて、記号や構文の情報、コードのコメント、およびアプリケーション構造全体からドキュメントを生成します。 このツールは、提供されたテンプレートに基づいて、こうした参考記事がアプリケーション構造に従って並べられたヘルプ サイトも生成します。

この記事では、ALDoc ツールを使用して AL .app パッケージのドキュメントを生成するために必要な手順について説明します。 ALDoc ツールは DocFx ツールに依存しているため、参照ドキュメントを生成するコンピューターで DocFx の前提条件を使用できる必要があります。

ALDoc ツールを使用してヘルプを生成するには、次の手順を実行します。

  1. DocFx と .NET の前提条件をインストールする

  2. .vsix ファイルから ALDoc ツールを取得する

  3. 参照ドキュメント ファイルを生成する

  4. 生成されたドキュメント用の静的 Web サイトを構築する

ALDoc ツールを使用するには、コンピューターに次の前提条件がインストールされている必要があります。

.NET 6.0 以上をインストールした後、DocFx ツールをインストールします。 DocFx は、静的サイトの生成に使用されるオープンソース ツールです。 .NET コードと XML コメントに基づいて参照ドキュメントを作成するように設計されています。 ALDoc ツールにより、DocFx を使用して AL オブジェクトのドキュメントを生成するためのサポートが追加されます。 詳細については、DocFx の基本的な概念を参照してください。

コマンド ライン ツールを管理者として起動し、次のコマンドを実行して .NET DocFx ツールのバージョン 2.70.0 をインストールします。これは、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

インストールが完了すると、DocFx ツールの最新バージョンをコンピューターで使用できるようになります。

ALDoc ツールは、Microsoft Dynamics 365 Business Central の AL 言語拡張機能に付属しており、以下に相当する場所にあります。

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

すべての前提条件が正常にインストールされたら、次の手順として、ALDoc ツールを使用してドキュメント ファイルを生成します。 そのためには、ドキュメントを生成する .app ファイルをコンピューターに用意しておく必要があります。 生成されたファイルを配置するフォルダーも用意しておく必要があります。

  1. まず、次のコマンドを指定して参照リポジトリを初期化します。 初期化することで、AL サポートファイルが展開され、DocFx 構成ファイル (docfx.json) を含む DocFx ツール用の入力フォルダーが作成されます。

    • コマンド構文

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

    • 例

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

  2. 次に、前の手順で指定した .app ファイルごとに参照ファイルを生成します。 ビルド コマンドは、ドキュメントを生成する .app ファイルごとに実行する必要があります。 さらに、相互参照のためには、ドキュメントを生成する依存 .app ファイル一式にビルド コマンドがアクセスできることが重要です。 これらのファイルは、-c パラメーターで指定します。

    • コマンド構文

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

    • 例

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

以降の手順では、DocFx ツールを使用して、静的 Web サイトを構築およびホストします。

ここまでの手順で、初期化ファイルと参照ファイルが生成されました。 これで、DocFx を使用して Web サイトを構築し、生成されたファイルをホストすることができます。この Web サイトは、ユーザーと内部または外部で共有できます。

  1. コマンド ラインで、次のようなコマンドを入力します。

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

  2. 次に、Web サイトをローカルにホストするために、次のようなコマンドを入力します。

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

  3. その後、ビルドが完了するまで待ち、ブラウザー ウィンドウに https://localhost:8080 と入力して、生成された Web サイトを確認します。 これで、目次が左側に表示され、生成された記事が右側に表示されます。

DocFx ツールを使い始める方法の詳細については、クイック スタートを参照してください。

自動生成されたコンテンツの一部の領域はそのままで機能し、構文に関する情報の提供、コード コメントの表示、アプリケーション構造全体の表示ができます。 しかし、自動生成されたコンテンツの中には、情報やガイダンス、備考を追加して価値を付加することが必要な領域もあります。 ALDoc ツールは、自動生成された記事の上書きをサポートしています。 上書きファイルには、自動生成されたコンテンツに挿入されたコンテンツが含まれています。自動生成されたコンテンツは上書きされません。 詳細については、「ALDoc ツールを使用したヘルプの上書き」を参照してください。