auto generated documentation and schema

[Antse]

Would be great if it is possible, based on parameters and variables descriptions to auto generated Documentation and Architecture schema like armviz.io

[alex-frankel]

Hi @Antse - can you share a bit more what you are looking for on documentation? Could you provide a code sample and the corresponding documentation you would want to see?

The visualization ask makes sense and we're definitely looking to see how we can light this up.

[Antse]

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]

Definitely an interesting proposal.

Do you think the output would be markdown?

[anthony-c-martin]

Great suggestion, this would be really useful! Would you mind creating an issue to track it?

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.

[brwilkinson]

Hi @Antse just checking in on this one, it would be best to move this over to an issue to track.

I may use the 'create issue from discussion' option on this one, however wanted to ensure it hadn't been moved over already ?

[brwilkinson]

I could not see anything current, so have now move this to a new issue #4935

@Antse was tagged in the new issue, I will mark this discussion as resolved.