[Feature Request]: Create a PoC for "Examples in readmes should allow modification of title and description"

Azure / ResourceModules

This repository includes a CI platform for and collection of mature and curated Bicep modules. The platform supports both ARM and Bicep and can be leveraged using GitHub actions as well as Azure DevOps pipelines.

https://aka.ms/carml

MIT License

724 stars 456 forks source link

[Feature Request]: Create a PoC for "Examples in readmes should allow modification of title and description" #1979

Open MariusStorhaug opened 2 years ago

MariusStorhaug commented 2 years ago

Description

Current module examples in readmes get titles from folder names in the modules .test folder.

Following how documentations is for PowerShell cmdlets, the examples have both title and descriptions next to the copy/pastable snippets. We should add automation to allow a test case/example to be adjustable with a custom title and description.

Test cases could also be written with contexts/scenarios in mind.

rahalan commented 2 years ago

Blocked because issue #1791 needs to be solved first

rahalan commented 2 years ago

Next step: create a PoC to discuss further

AlexanderSehr commented 2 years ago

Some ideas that were discussed:

Have a metadata file (e.g. JSON) for the tests to place additional content there - and include it when generating the readme
OR have the metadata in the deploy.test.bicep file itself. For example with a specific syntax on the top of the file so that we could extract it when generating the deployment examples
OR have the metadata in the deploy.test.bicep file itself, but trying to leverage the ARM 'metadata' object that is generated when compiling bicep to ARM. There may be a counter-part in native Bicep.

rahalan commented 2 years ago

After PoC is presented, team will decide how to proceed