fix: generate documentation without template literals and with standard headers#194
Conversation
zimeg
added
bug
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #194 +/- ##
==========================================
- Coverage 63.07% 62.90% -0.17%
==========================================
Files 212 212
Lines 21672 21782 +110
==========================================
+ Hits 13670 13703 +33
- Misses 6953 7013 +60
- Partials 1049 1066 +17 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
zimeg
left a comment
zimeg
left a comment
There was a problem hiding this comment.
💌 Notes on updates follow for the kind reviewers but also please find in an expected diff:
- "Synopsis" is changed to "Description"
- "Options" is changed to "Flags"
- "Options inherited from parent commands" is changed to "Global flags"
- "SEE ALSO" is changed to "See also"
| if len(cmd.Example) > 0 { | ||
| fmt.Fprintf(buf, "## Examples\n\n") | ||
| fmt.Fprintf(buf, "```\n%s\n```\n\n", cmd.Example) | ||
| } | ||
| if err := genMarkdownCommandFlags(buf, cmd); err != nil { | ||
| return err | ||
| } |
There was a problem hiding this comment.
👁️🗨️ note: This ordering might be updated in a follow up PR to match --help outputs.
| Remediation: fmt.Sprintf("Choose a specific app with %s", style.Highlight("--app <app_id>")), | ||
| Remediation: "Choose a specific app with `--app <app_id>`", |
There was a problem hiding this comment.
Highlight since styles are not found in these error messages - the error map is compiled without styles toggled "on".
🐣 note: This matches the fallback behavior of Commandf and ought not cause problems in output. An example command might use "--app ..." as an option to show this.
mwbrooks
left a comment
mwbrooks
left a comment
There was a problem hiding this comment.
✅ Beaaaauty! Love this change, thank you!
🧪 Tested locally and all the changes are either expected or improvements (updating stale content).
| // Cobra are a group of Cobra functions shared by all packages and enables tests & mocking | ||
| Cobra struct { | ||
| // GenMarkdownTree defaults to `doc.GenMarkdownTree(...)` and can be mocked to test specific use-cases | ||
| // TODO - This can be moved to cmd/docs/docs.go when `NewCommand` returns an instance of that can store `GenMarkdownTree` as | ||
| // a private member. The current thinking is that `NewCommand` would return a `SlackCommand` instead of `CobraCommand` | ||
| GenMarkdownTree func(cmd *cobra.Command, dir string) error | ||
| } |
| return err | ||
| } | ||
| if hasSeeAlso(cmd) { | ||
| fmt.Fprintf(buf, "## See also\n\n") |
There was a problem hiding this comment.
ignore-me: While I prefer "Title Case", this looks correct because our docs use "Sentence case". I think it's best for the CLI to stay aligned with our docs. So please ignore me! 🧠
|
@mwbrooks @lukegalbraithrussell Appreciate the kind reviews so much. I'm excited for all the more customizations possible from these changes. But for now let's merge this. 🚢 💨 |
3 participants
Summary
This PR removes template literals and changes headers of generated documentation to match previous build scripts used for upstream pages 📚 ✨
Reviewers
With these changes checked out, confirm expected updates to reference are found:
Requirements