/
/
Geautomatiseerd documentatie genereren

Geautomatiseerd documentatie genereren

In deze blog laat Maik van der Gaag je zien hoe je in Azure DevOps geautomatiseerd documentatie kunt genereren. Laat je inspireren in deze blog, veel leesplezier!

Onlangs liet ik tijdens mijn presentatie (You Build It, You Run It on the Microsoft Platform) bij het Azure Lowlands online evenement, een script zien waarin veel mensen geïnteresseerd zijn.

De presentatie gaat over het opzetten van software / een product wat na oplevering ook draaiende gehouden moet worden. In deze nieuwe tijd waarin DevOps veel besproken is, zien we hierin een nieuwe manier van werken. Tijdens de sessie laat ik dan ook een aantal Cloud Native diensten zien die iedereen in zijn dienst kan gebruiken.

Naast deze diensten komen er in de presentatie een aantal zaken langs die wij (Leon Boers en ik) hebben ontwikkeld tijdens onze werkzaamheden voor verschillende projecten. Eén van onze principes in DevOps-teams is het verbeteren van de dagelijkse werkzaamheden. Dit gaat bijvoorbeeld over het maken van een automatisering tot het vastleggen en verbeteren van werkprocessen: geautomatiseerd documentatie genereren.

Eén van de verbeteringen die wij ooit hebben doorgevoerd is een script voor het documenteren van de scripts (PowerShell) en ARM templates. Door de inzet hiervan zijn belangrijke zaken inzichtelijk voor andere mensen die ermee gaan werken en is er vrijwel geen extra werk voor de ontwikkelaars.

Deze scripts genereren op basis van bestanden (ps1 / json) markdown files die je als documentatie kan gebruiken in een wiki op GitHub of Azure DevOps.

Wil je de presentatie terugkijken? Klik dan hier.

PowerShell

De PowerShell script documentatie generatie is gebaseerd op een script wat we ooit tegen kwamen op GitHub. De documentatie wordt gegenereerd op basis van de help-informatie die iemand kan plaatsen in een PowerShell script. Deze informatie geeft iedereen die met het script werkt het inzicht en wat het script kan en hoe deze werkt.

<#
.SYNOPSIS
    Script for generating Markdown documentation based on information in PowerShell script files.
.DESCRIPTION
    All PowerShell script files have synopsis attached on the document. With this script markdown files are generated and saved within the target folder.
.PARAMETER ScriptFolder
    The folder that contains the scripts
.PARAMETER OutputFolder
    The folder were to safe the markdown files
.PARAMETER ExcludeFolders
    Exclude folder for generation. This is a comma seperated list
.PARAMETER KeepStructure
    Specified to keep the structure of the subfolders
.PARAMETER IncludeWikiTOC
Include the TOC from the Azure DevOps wiki to the markdown files
.NOTES
    Version:        1.0.0;
    Author:         3fifty | Maik van der Gaag | Leon Boers;
    Creation Date:  20-04-2020;
    Purpose/Change: Initial script development;
.EXAMPLE
    .\New-MDPowerShellScripts.ps1 -ScriptFolder "./" -OutputFolder "docs/arm"  -ExcludeFolder ".local,test-templates" -KeepStructure $true -IncludeWikiTOC $false
.EXAMPLE
    .\New-MDPowerShellScripts.ps1 -ScriptFolder "./" -OutputFolder "docs/arm"
#>

In de documentatie generatie is voor ons een specifieke toepassing toegevoegd voor het Notes field van de helpsectie. In het Notes field hanteren we de specificatie [Naam]: [Waarde]; om specifieke informatie omtrent het script te kunnen delen maar deze ook goed te kunnen formateren.

Met behulp van deze informatie wordt er uiteindelijk een MarkDown bestand opgeleverd die je kan gebruiken voor de documentatie.

ARM templates

Toen de documentatie generatie voor PowerShell werkte zijn we gaan kijken of we het zelfde principe ook konden toepassen voor andere bestanden. We zijn toen direct gaan kijken naar het documenteren van onze ARM templates. We schreven er heel veel en ze werden niet gedocumenteerd.

De documentatie voor ARM templates worden gegenereerd gebaseerd op de informatie die standaard aanwezig is binnen de templates waar informatie wordt getoond binnen de documentatie over de parameters, variables, resources en output.

Om extra informatie over de templates te krijgen, is de “metadata” property toegevoegd. Een voorbeeld van deze property kan je hieronder zien:

"metadata": {
     "Description": "This template deploys a standard storage account.",
     "Author": "3fifty | Maik van der Gaag | Leon Boers",
     "Version": "1.0.0"
}

Aan de hand van de “description” wordt er een omschrijving toegevoegd aan de documentatie. Alle overige properties zijn netjes geformateerd. Dit betekent dus dat je er zelf voor zou kunnen kiezen om extra properties toe te voegen.

Automation

Zoals je wellicht verwacht, zijn deze scripts te automatiseren door ze in een Azure DevOps Pipeline te plaatsen. Onderstaande yaml geeft weer hoe je dit kan doen.

- task: PowerShell@2
  displayName: 'Docs - Generate scripts documentation'
  condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))
  inputs:
    filePath: './utilities/New-MDPowerShellScripts.ps1'
    arguments: '-ScriptFolder "$(scriptPath)" -OutputFolder "$(scriptDocPath)"'
    pwsh: true

De scripts zijn geplaatst in een GitHub repository van 3fifty. Neem daar gerust een kijkje.

3fifty/scripts: A repository with scripts and files that are shared with the community. (github.com)

Meer weten over Azure DevOps?

Wil je meer weten over DevOps of Azure DevOps? Maik geeft interessante en leerzame trainingen. Bekijk de trainingen op onze trainingspagina. Maik schreef ook meerdere blogs zoals “Het beheren van de Microsoft Azure cloud is niet eenvoudig” en ” Wat kan Azure DevOps voor jou betekenen?”

Auteur

Maik

2 februari 2021

Bekijk ook