Bicep.LocalDeploy 1.0.1

The Bicep.LocalDeploy.DocGenerator project is a documentation tool to generate Markdown files based on .NET Bicep models. It assists by reading the attributes from the model you have defined for your Bicep local-deploy and generating reference documentation(examples, arguments, and outputs).

The bicep-local-docgen command-line utility (CLI) has two options available:

• generate: Generate documentation files from Bicep models.
• check: Check if models have available attributes to leverage in documentation

Each subcommand provides help information. If you call bicep-local-docgen generate --help, it shows you the help description for the options available.

Getting started

To install the CLI utility globally, use the following command:

dotnet tool install bicep-local-docgen -g

Then, target a directory containing your Bicep model files. For example, the following command generates documentation in the Models directory:

bicep-local-docgen generate --source Models

The CLI's default output is the docs directory. Use the --output or --pattern options to customize the behavior of the CLI. If you want to see verbose message, add the --verbose option to log messages to the console.

For the full documentation, check it out on GitHub.

Using attributes for documentation

This project includes a .NET library that can be used to customize the rendered Markdown output. In .NET, you use attributes to annotate your models. Add the Bicep.LocalDeploy package to your project to use them.

To add the library to your project, simply run the following command:

dotnet add package Bicep.LocalDeploy

You can annotate your models with these attributes:

• [BicepDocHeadingAttribute]: Sets the first heading (H1) title and its description.
• [BicepFrontMatterAttribute]: Adds YAML front matter key/value pairs.
• [BicepDocExampleAttribute]: Adds example blocks (title, description, code[, language]).
• [BicepDocCustomAttribute]: Adds custom sections (title, description).

For example, imagine you've defined the following Bicep model:

using Azure.Bicep.Types.Concrete;
using Bicep.Local.Extension.Types.Attributes;
using System.Text.Json.Serialization;

namespace MyOwnModel;

[ResourceType("MyOwnResource")]
public class MyOwnResource : DirectoryIdentifiers
{

}

public class MyOwnResourceIdentifiers
{
    [TypeProperty("A demo resource.", ObjectTypePropertyFlags.Required | ObjectTypePropertyFlags.Identifier)]
    public required string Resource { get; set; }
}

When you run the bicep-local-docgen tool, the produces output will be:

# MyOwnResource

Manages MyOwnResource resources.

## Example usage

### Basic MyOwnResource

Creating a basic MyOwnResource resource:

```bicep
resource myOwnResource 'MyOwnResource' = {
}
```

If you add annotations in the following way:

[BicepDocHeading("My Own Resource", "Example resource used to demonstrate documentation generation.")]
[BicepFrontMatter("category", "resource")]
[BicepDocExample(
        "Basic deployment",
        "Minimal example creating the resource.",
        @"resource my 'MyOwnResource' = {
Resource: 'my-resource'
}")]
[BicepDocCustom("Custom Section", "This is a custom section.")]
// Rest of the code

The produces output is the following Markdown:

---
category: "resource"
---

# My Own Resource

Example resource used to demonstrate documentation generation.

## Example usage

### Basic deployment

Minimal example creating the resource.

```bicep
resource my 'MyOwnResource' = {
Resource: 'my-resource'
}
```

## Custom Section

This is a custom section.