ALZ Bicep - Generate Markdown for Parameters #304

4pplied · 2022-08-19T10:08:25Z

Overview/Summary

Created GH Actions Workflow which generates Markdown from Bicep files leveraging PSDocs for Azure.

In order, this will:

Workflow triggered from push on 'main' with Bicep files as path as condition
Check out the repository
Perform a Bicep build on each of the modules to create ARM Templates (JSON)
Add two additional key value pairs to the templates. Name, which corresponds to the name of the Bicep file. Description, brings in an 'Up a level' hyperlink.
Generates Markdown from the templates
Removes the ARM Template files, leaving just the Bicep and the generated Markdown
Commits and pushes the markdown if any changes are needed
A hyperlink to the generated markdown files has already been inserted and replaces the parameters table in each of the static README.md's for standardisation across the board.

This PR fixes/adds/changes/removes

Adds GitHub Workflow for MD Generation for modules
Removes parameter tables from static readme's, link to new generated MD inserted

Breaking Changes

N/A

Testing Evidence

As part of this Pull Request I have

jtracey93 · 2022-08-31T11:56:37Z

Great work, @JamJarchitect

As discussed on our call a few minutes ago, there are some additional test cases that we need to think about here.

These are all based on the fact that I believe the GitHub action will not run successfully in the main Azure/alz-bicep repo due to the branch protection policies that are in place upon the main branch.

Therefore, can I ask that you have a think and create some tests and test it out yourself? For handling. Updates into a pull request or the branch that is associated from an external users pull request into the main branch on perhaps a fork for testing (would be azure/alz-bicep main in reality).

If we can make the workflow update the branch that the pull request has originated from. Then I think this is the best option.

I have placed the do not merge label on this PR and will await your updates on this topic.

👍👍

jtracey93

Also @JamJarchitect, could we make the parameter docs page for each module, link back up to the specific module README.md instead of the root of the modules directory?

Also could we look at adding parameter type information to the table? e.g. whether the parameter is an array, object, string etc.? This data is available in the bicep/arm tempalte so should be possible if supported in PSDocs

ghost · 2022-09-07T12:01:38Z

This pull request has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 7 days. It will be closed if no further activity occurs within 7 days of this comment.

jtracey93 · 2022-09-07T12:16:20Z

This is still active

ghost · 2022-09-14T15:01:26Z

This pull request has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 7 days. It will be closed if no further activity occurs within 7 days of this comment.

jtracey93 · 2022-09-14T15:22:22Z

Still active

ghost · 2022-09-21T18:01:51Z

This pull request has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 7 days. It will be closed if no further activity occurs within 7 days of this comment.

jtracey93 · 2022-09-21T18:14:26Z

still active

ghost · 2022-09-28T21:01:23Z

This pull request has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 7 days. It will be closed if no further activity occurs within 7 days of this comment.

jtracey93 · 2022-11-03T19:08:50Z

@JamJarchitect can we fix the merge conflicts

4pplied · 2022-11-07T13:02:57Z

/azp run e2e

azure-pipelines · 2022-11-07T13:03:09Z