Generazione della guida con lo strumento ALDoc

  • 6 minuti

Per facilitare l'uso delle app a valle, la documentazione rappresenta un grande vantaggio. Finora, serviva un processo manuale per crearla e mantenerla aggiornata con le modifiche apportate, a meno che l'editore non avesse investito in automazione.

Per gli editori di estensioni, forniamo un nuovo strumento ALDoc.

Lo strumento ALDoc genera documentazione da informazioni simboliche e sintattiche, commenti sul codice e una struttura applicativa generale basata su file .app di input. Puoi utilizzarlo per generare documentazione di riferimento interna o esterna per la tua soluzione.

Lo strumento genera anche un sito della Guida con articoli di riferimento ordinati in base alla struttura applicativa, a seconda del modello personalizzato fornito.

La generazione di contenuti basati sul codice sorgente presenta numerosi vantaggi, tra cui precisione, rappresentazione al 100% della base di codice corrente, documentazione meno soggetta a errori e risparmio di tempo. Lo strumento ALDoc genera documentazione da informazioni simboliche e sintattiche, commenti sul codice e una struttura applicativa generale basata su file .app di input. Lo strumento genera anche un sito della Guida con questi articoli di riferimento ordinati in base alla struttura applicativa, a seconda del modello personalizzato fornito.

Questo articolo descrive i passaggi necessari per usare lo strumento ALDoc per generare la documentazione per i pacchetti .app AL. Lo strumento ALDoc si basa sullo strumento DocFx e richiede la disponibilità dei prerequisiti DocFx sulla macchina che genera la documentazione di riferimento.

Per generare la Guida usando lo strumento ALDoc, è necessario eseguire i seguenti passaggi:

  1. Installare i prerequisiti di DocFx e .NET

  2. Ottenere lo strumento ALDoc dal file .vsix

  3. Generazione dei file della documentazione di riferimento

  4. Creazione di un sito Web statico per la documentazione generata

Per usare lo strumento ALDoc, è necessario che sul computer siano installati i seguenti prerequisiti.

Installare lo strumento DocFx dopo aver installato .NET 6.0 o versioni successive. DocFx è uno strumento open source usato per generare siti statici. È progettato per creare documentazione di riferimento basata su codice .NET e commenti XML. Lo strumento ALDoc aggiunge il supporto per la generazione di documentazione per oggetti AL con DocFx. Per altre informazioni, vedere Concetti di base in DocFx.

Avviare uno strumento da riga di comando come amministratore ed eseguire il comando seguente per installare lo strumento .NET DocFx, versione 2.70.0, la versione consigliata più recente per 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

Al termine dell'installazione, si disporrà della versione più recente dello strumento DocFx sul computer.

Lo strumento ALDoc viene fornito con l'estensione in linguaggio AL per Microsoft Dynamics 365 Business Central ed è disponibile nella posizione equivalente di:

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

Dopo aver installato correttamente tutti i prerequisiti, il passaggio successivo consiste nell'usare lo strumento ALDoc per generare i file della documentazione. A tale scopo, è necessario disporre sul computer dei file .app per i quali si vuole generare la documentazione. È inoltre necessario disporre di una cartella in cui inserire i file generati.

  1. Innanzitutto, inizializzare il repository di riferimento fornendo il seguente comando. L'inizializzazione decomprime i file di supporto AL e crea la cartella di input per lo strumento DocFx, incluso il file di configurazione di DocFx (docfx.json).

    • Sintassi di comando

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

    • Esempio

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

  2. Successivamente, generare i file di riferimento per ogni file .app specificato nel passaggio precedente. È necessario eseguire il comando build per ogni file .app per cui si vuole generare la documentazione. Inoltre, è importante per i riferimenti incrociati che il comando build abbia accesso al set completo di file .app dipendenti per cui si vuole generare la documentazione. Specificare questi file con il parametro -c.

    • Sintassi di comando

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

    • Esempio

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

Nei passaggi successivi si userà lo strumento DocFx per creare e ospitare il sito Web statico.

Nei passaggi precedenti si sono generati i file di inizializzazione e di riferimento. È ora possibile usare DocFx per creare un sito Web per ospitare i file generati, che è possibile condividere con gli utenti internamente e/o esternamente.

  1. Nella riga di comando inserire un comando equivalente a questo:

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

  2. Successivamente, per ospitare il sito Web in locale, inserire un comando equivalente a questo:

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

  3. Attendere il completamento della compilazione e in una finestra del browser quindi digitare https://localhost:8080 per controllare il sito Web generato. Ora si dovrebbe vedere il sommario a sinistra e gli articoli generati a destra.

Per altre informazioni sulle attività iniziali con lo strumento DocFx, vedere Avvio rapido.

Alcune aree del contenuto generato automaticamente funzionano così come sono, fornendo informazioni sulla sintassi, mostrando eventuali commenti sul codice e visualizzando la struttura complessiva dell'applicazione. Altre aree del contenuto generato automaticamente potrebbero richiedere ulteriori informazioni, indicazioni o osservazioni per aggiungere valore. Lo strumento ALDoc supporta la sovrascrittura degli articoli generati automaticamente. Un file di sovrascrittura contiene contenuto inserito nel contenuto generato automaticamente e non sovrascrive il contenuto generato automaticamente. Per altre informazioni, vedere Sovrascrittura della guida con lo strumento ALDoc.