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

[MariusStorhaug]

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]

Blocked because issue #1791 needs to be solved first

[rahalan]

Next step: create a PoC to discuss further

[AlexanderSehr]

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]

After PoC is presented, team will decide how to proceed