Add docs command proposal for CLI docs generation#19694
Conversation
|
|
||
| ### Proposed syntax and package | ||
|
|
||
| Use `Scriban` as the templating engine. |
There was a problem hiding this comment.
I like the idea of picking an existing templating language to avoid reinventing the wheel, but we should consider the options very carefully there. My concerns would be:
- This is a decision that's hard to undo without breaking people, and so we should make sure we take into consideration things like popularity and OSS-friendliness / licensing models.
- My understanding is that Scriban is a popular choice for .NET developers, but I'm not sure what usage looks like across the board - we should make sure we take into consideration people coming from different backgrounds.
There was a problem hiding this comment.
I researched this multiple times with different tools and models. Each one came back with the same answer of using the Scriban package as the best option. I've added an appendix that compares the different options and explains the decision. Hope that is useful. Scriban is fully compatible with Liquid syntax, but also adds some additional features. It is well maintained and used extensively, so I agree it is likely the best choice here.
| bicep docs generate ./modules/storage/main.bicep | ||
|
|
||
| # Recursively generate README.md for all discovered modules | ||
| bicep docs generate ./modules --recursive |
There was a problem hiding this comment.
In other command groups we use --pattern (for example bicep build --pattern '**/*.bicep'). I would recommend aligning for familiarity.
There was a problem hiding this comment.
This is done and updated.
| | `--preset <name>` | Built-in template preset selector. Defaults to `markdown`. The only supported preset in v1 is `markdown`. When `--template-file` is provided, rendering is determined by that template and `--preset` is validation/default-selection metadata only. | | ||
| | `--template-file <path>` | Path to a custom template file. If omitted, the built-in default Markdown template is used. | | ||
| | `--template-root <path>` | Optional override for include resolution root. By default, include paths are resolved relative to the module being processed. | | ||
| | `--set <key=value>` | Supplies a custom string value that is exposed to the template model for use by custom Scriban templates. May be specified multiple times. | |
There was a problem hiding this comment.
Could you give some example use-cases for this? The user will have control over the custom template, so what scenarios are there where someone would want to pass in custom information instead of hard-coding it into the template?
There was a problem hiding this comment.
We provide some examples in the Custom string values section for why you might want this. IT is essentially any information that can't be gleaned from the bicep code, such as references to doc urls, module owners, etc.
…s to .md, add appendix and rationale
…VM PowerShell tooling, standard for module docs)
2 participants
Summary
bicep docscommand group indocs/experimental/docs-command.mdgenerateandoutputsubcommands and their expected behavior--setvaluesNotes
Microsoft Reviewers: Open in CodeFlow