Enhanced docs gen to more closely match existing docs (legacy) #692
Conversation
prasek
changed the title
| for _, options := range w.optionsStack { | ||
| allOptions = append(allOptions, options...) | ||
| } | ||
| if len(c.Children) == 0 { |
There was a problem hiding this comment.
Great improvement here! The old code fails to handle a few edge cases with more complex subcommands.
How are Parent and Children used? I only see Children being used to check if len(c.Children) == 0 {, and I don't see the Parent information used anywhere. If that's the case, I feel like a simpler approach would be to keep a IsLeafCommand from enrich.go and use that for this condition here
There was a problem hiding this comment.
@yuandrew Thanks! Parent is used in EnrichCommands() for various things including setting Children on the Parent. Are you thinking an IsLeafCommand() helper or something on the Command struct?
Children gives docs.go more flexibility in how the docs are rendered, for example the more hierarchical docs gen style used in this tcld PR which we probably want to move to for temporal at some point.
## What was changed - Updated `commands.yml` to address feedback on temporalio/documentation#3149 (comment) - Intended for use with the following, but also is fine to merge standalone - #691 - #692 See this branch for [the combined approach](https://github.com/prasek/temporal-cli/tree/cli-docs-gen-all) with all PRs merged in. ## Why? To create CLI docs for Nexus. ## Checklist 1. How was this tested: - `go run ./temporalcli/internal/cmd/gen-docs ` - also tested with [the combined appraoch](https://github.com/prasek/temporal-cli/tree/cli-docs-gen-all) - copied generated docs (or subset) to temporalio/documentation - `yarn start` - verified via http://localhost:3000/ Ran `go test ./...` Tested locally with: ``` go run ./cmd/temporal operator nexus endpoint create --name myendpoint --target-namespace my-target-namespace --target-task-queue my-handler-task-queue --description '## Sales Services Workflow'\''s to support Customer-to-Order generation. ## other stuff ' ``` 2. Any docs updates needed? - overall docs gen needs more alignment with the existing docs, but that is out of scope for these Nexus changes - will update temporalio/documentation#3149 with cherry picked generated content from [the combined approach](https://github.com/prasek/temporal-cli/tree/cli-docs-gen-all). --------- Signed-off-by: Phil Prasek <[email protected]> Signed-off-by: Josh Berry <[email protected]>
temporalcli/commandsgen/enrich.go
Outdated
There was a problem hiding this comment.
I don't think this separate concept needs to exist. Just put inside parse or put inside docs.
There was a problem hiding this comment.
sounds good, will combine.
Signed-off-by: Phil Prasek <[email protected]>
Signed-off-by: Phil Prasek <[email protected]>
Signed-off-by: Phil Prasek <[email protected]>
Signed-off-by: Phil Prasek <[email protected]>
Signed-off-by: Phil Prasek <[email protected]>
prasek
changed the title
|
Incorporated feedback into #691. Think we can close this PR as legacy docs / will not merge - since we're moving away from This PR may be useful for generating legacy docs during the transition. |
Note
Not for merging, only for reference for generating legacy docs during the transition.
What was changed
cmd-options.mdxwith collated on option descriptioncmd-options.mdxSee this branch for the combined approach with follow-on PRs merged in.
Note: longer term would recommend moving away from
cmd-options.mdxand to an inline options model similar to howtclddocs works, as some option names likename,build-id, andyeshave lots of overlapping definitions and some are specific to command usage.Why?
Needed updated
operator.mdxandcmd-options.mdxoutput for Nexus docs and wanted to use docs gen.Checklist
go run ./temporalcli/internal/cmd/gen-docsyarn start