joachimdalen/bicepdocs

A tool to build documentation for Bicep modules

Hi there 👋

Hi, I'm Joachim! Nice of you to stop by. Let me tell you a little bit about me and what I do.

I'm a Cloud Solutions Architect specializing in Azure, Azure DevOps and .NET.

My main focus areas revolves around:

• Infrastructure Engineering
• Developer Experience
• Automation

I also enjoy the challenges that comes with desiging software and infrastructure architecture.

Projects

Currently not working on anything :(

My repositories

Like many other developers I have a lot of unfinished projects and a lot of them you fill find under this project. I tend to not delete any projects, but that does not mean I will come back to them. Feel free to submit an issue on any of them if you have any questions.

Azure Certified

Identity and Access Administrator Associate	Azure Security Engineer Associate	Azure Developer Associate
DevOps Engineer Expert	Azure Solutions Architect Expert	Security, Compliance, and Identity Fundamentals

CompTIA Certified

CompTIA CTT+ Classroom Trainer

bicepdocs's Issues

Pull request template improvements and fixes

• Contribution guidelines are missing the link
• Make agreement a checkbox

Introduce proper naming for generation sequence concepts

We have three different dynamics used in the tools:

• Sources: Where we should load the files from, e.g File system, ACR
• Formatters: The format to convert the bicep files to, e.g Markdown
• Destinations: The target of where formatted files should be written to, e.g Filesystem

The flow of converting a file is:

flowchart LR
    Source --> Formatter
    Formatter --> Destination

Sources

• Contains the commands for the CLI to load bicep files from the source

Formatters

• Takes in general objects with the data needed

Destinations

• Takes in general objects and writes the files

TODO:

• Rename projects
• Refactor code
• Update documentation

Improve formatting of code examples and default values

Improve code formatting of:

• Default values for parameters
• Code examples
• Allowed values

Add referenced resources section

Add a new section for all resources using the existing keyword to make it easier to see what dependencies a module has.

Lint generated markdown files

Lint generated markdown files using https://github.com/DavidAnson/markdownlint

Add Azure Pipelines extension for running bicepdocs

• Tasks to:
  • Install tool
  • Generate documentation

Update dependencies

Version option is returning the wrong version

bicepdocs --version is not returning the correct version

Support User-defined data types

Confluence destination

A provider to create and upload documentation to a set of Confluence pages

Setup versioning and GitHub releases

• Versioning
  • Setup versioning of tool based on tag version
  • Create GitHub release
• Improve builds
  • Build and test matrix on PR
  • Remove merge build
• Improve docs
  • Add install documentation like: https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install
• Improve installation
  • Add homebrew tap and formula - joachimdalen/homebrew-bicepdocs#1

Prepare repo for public visibility

• Add issue templates
• Add Contributing
• Add getting started steps

Resolve compilation warnings

Improve release note generation

Improve release notes section:

• Add release.yml file with configuration

Use correct values for code examples

Improve the code examples to use more accurate values:

• Registry module vs local module
• Module path
• Module name and version

Work on this project

Project kinda died for a while, but time to see if it can improve:

• Get overview over what is done
• Update all packages
• Finish started features

Add Github Action for running bicepdocs

Add e2e tests for documentation generation

Add E2E tests for documentation generation using Azure Resource Modules. These test should be ran for each of the platform compiled binaries and against all providers to ensure correct output.

• Create repository for test data
• Download Azure - ResourceModules for input data
• Create test data
• Add configuration to pipelines
  • Download resource modules
  • Download test data

Issues when using relative paths

Improve installation experience for Windows users

Upgrade .NET version

The latest versions of the Bicep SDK does not support .NET 6. Need to upgrade the .NET version to be compatible with the SDK.

Files does not load on Windows

Fix deprecated set-output

The build workflow uses the set-output command which is deprecated, must be updated to use Environment files

Documentation generation from modules uploaded to a Azure Container Registry

Ability to generate documentation from modules already uploaded to a Azure Container Registry

• Add new command
  • Options for RegistryName and authentication
• Read modules from registry
• Option to add registry path to generated documentation
• Update documentation

Add markdown rule MD047 to resulting .md files (Files should end with a single newline character)

What formatter are you using?

Markdown

Bicep version

v0.23.1

Bicepdocs version

0.1.2

What operating system are you using?

Windows

What is the bug you want to report?

Missing a single newline character at the end of the .md files, so they follow markdownlint rules, specifically MD047.

Azure DevOps Wiki documentation destination

A provider to create and upload documentation to a set of Azure DevOps Wiki pages

Include constraints for parameters

Setup build and release in Actions instead of Azure Pipelines

• Create workflow to build and test
• Create workflow to build binaries