Generate Azure Bicep documentation with PSDocs! 💪🏻
Creating documentation can be boring, but what if I told you that you can generate documentation for your Bicep code? PSDocs makes it possible! For this demo, I’ve chosen one of my older solutions. However, I never got around to creating a proper README.md file for it…
I created a simple PowerShell function to generate the Bicep docs using the PSDocs PowerShell Module!
- The first step in this function is to ensure the PSDocs module is installed on our machine.
- Next, it uses
Bicep Buildto convert the Bicep file into an ARM template, as PSDocs only works with ARM templates. - Finally, the function invokes the
PSDocumentcmdlet to generate a README.md file based on the ARM template.
PSDocs uses the metadata.json-file to fill for example the name and description based on the metadata value in your Bicep code.
Using main.bicep as the input file and markdownFiles as the output folder the function stores the README.md in a separate folder for tests. You can simply do this with Invoke-BicepDocumentation -bicepFilePath ".\main.bicep" -outputFolderPath ".\markdownFiles" 🔥
Afterwards, we have a README.md file that can be used in our repositories. This file provides a comprehensive overview of all possible parameters, clearly indicating which parameters are required and which are optional.
The README.md file also includes details about the outputs you’re generating. For instance, in this case, it specifies the outputs afwSubnet and afwMgmtSubnet. For the complete test README.md file, see my GitHub.
I must say, PSDocs is incredibly handy for generating clean documentation. Now, I no longer need to create code documentation manually; I can simply generate it! 🚀 That’s all for today! Feel free to share your feedback, and I look forward to our next session. Until then, take care! ❤️
