Auto generated documentation e.g. Markdown and schema

[brwilkinson]

Originally posted by @Antse in #2301 (comment)

by auto generated documentation i mean something like : (must confess i take some example from the official documentation)

Code :

@description('This is the storage account Name')
param stoName string

@description('This is my secure param')
@secure()
param secureParam string

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: stoName // must be globally unique
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
  tags: {
    'env':secureParam
  }
}

Doc :

Deploy a Storage Account

Overview (global deployed resources schema)

Parameters

stoName

• Type
  string
• Default value
  None
• Description
  This is the storage account Name

secureParam

• Type
  secure string
• Default value
  None
• Description
  This is my Secure Param

Examples

Deploy Bicep file to a resource group

Az CLI:

az deployment group create -f ./main.bicep -g my-rg

Azure PowerShell:

New-AzResourceGroupDeployment -TemplateFile ./main.bicep -ResourceGroupName my-rg

Note: make sure you update the default value of the stoName parameter to be globally unique before deploying.

Deploy with parameters

Our Bicep file exposed two parameters that we can be optionally overridden (secureParam and stoName) by passing new values at deployment time.

Pass parameters on the command line

Az CLI:

az deployment group create -f ./main.bicep -g my-rg --parameters secureParam=MySecretParam stoName=uniquelogstorage001

Azure PowerShell:

New-AzResourceGroupDeployment -TemplateFile ./main.bicep -ResourceGroupName my-rg -location westus -stoName uniquelogstorage001 -secureParam MysecretParam

[brwilkinson]

Adding @anthony-c-martin comments (from #2301 discussion) below:

IMO, the biggest challenge here will be giving users the level of customizability they want; I feel that everyone will have a slightly different expectation around how documentation should be formatted, and what information is relevant.

It's also quite likely we're going to need to documentation generation capabilities as part of #62.

This should be aided by #1665.

[matsest]

Been using this PSDocs module in a pipeline to build documentation for both ARM templates and Bicep modules (bicep build as a pre step for simple parsing from JSON in Powershell). It's rather flexible thanks to the templating features of PSDocs.

See example of ARM template doc generation here:
https://github.com/microsoft/PSDocs/blob/main/docs/scenarios/arm-template/arm-template.md))

[RossMurr4y]

Would this include a visual diagram of deployed resources similar to that of the Visualiser? It's not clear to me if that's what is being portrayed in the "Overview" section above, or if this is just a list of icons.

[brwilkinson]

@RossMurr4y

There is a few more snippets of context in the original discussion #2301

I think this is more about 'Docs' style output that you would have on a wiki or docs webpage Etc.

Perhaps if you think about the Public Module gallery, it might be something that you can search and directly reference when using Module from the Gallery or even knowing if you want to use a particular Module.

So it's more of a what you see above (and the image below) is a visualization on 'How to' use a Module etc.

I think comparing it to the PowerShell docs pages, might make a good comparison?

• if I want to know how to use get-process I can look at the docs page.

help get-process -online

Which directly here:
https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-process

So I think something like that.

Seems like the visualization would also be useful on that same page and there are some other requests that have been opened to be able to export out the visualizations from vscode #2704

[BernieWhite]

I think some a @example() attribute on the parameter would be helpful both from an authoring and documentation point of view.

Working in the problem space a lot, when an array or an object need to be passed into a module/ template it's always hard to consume. What properties can be used is hard to determine. Typically the default value doesn't work because it is often set to an empty string, array or the parameter may be required. Having a prototype of the object to build work nicely.

Here is how we do it in PSDocs for Azure. https://github.com/Azure/PSDocs.Azure/#annotate-templates-files currently, but there is no specific support in Bicep to allow this prototype to be show as a tip or added.

@metadata({
  example: {
    env: 'Prod'
    service: 'SERVICE_NAME'
  }
})
param tags

[alex-frankel]

Working in the problem space a lot, when an array or an object need to be passed into a module/ template it's always hard to consume. What properties can be used is hard to determine. Typically the default value doesn't work because it is often set to an empty string, array or the parameter may be required. Having a prototype of the object to build work nicely.

I think this is a good idea, but is treating a symptom and not the cause. We need to support user-defined types (#4158) so that the editor can provide completions and validate object parameters with a specific schema.

cc @rynowak as FYI

[BernieWhite]

@alex-frankel Absolutely agree. But when it hits the wire format JSON, there is no reason it can't be articulated as a well known metadata property like description. Which doesn't leave other tooling in the dark.

Example:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "workspaceId": {
            "type": "string",
            "metadata": {
                "description": "The resource identifier for a Log Analytics workspace.",
                "strongType": "Microsoft.OperationalInsights/workspaces"
            }
        }
    }
}

[alex-frankel]

Agreed. That metadata needs to manifest itself in the JSON layer as well. I think #4158 will address what you are looking for.