Improved docs gen #691

prasek · 2024-10-15T19:32:35Z

What was changed

Improved Command model for simpler docs rendering
Rendered inline options under each command, without cluttering up the right side nav.
Acorn rendering fix for JSON examples in .mdx
Add rendering of experimental options.

Why?

Nexus docs need to be created and want to use docs gen.

Checklist

How was this tested:

go run ./temporalcli/internal/cmd/gen-docs
verified via http://localhost:3000/

Any docs updates needed?

will feed into overall docs cleanup

CLAassistant · 2024-10-15T19:32:41Z

All committers have signed the CLA.

yuandrew

Left some small nit comments, but I'm not sure the split between this PR and #691 is what we want. I think the split we want is:

The cmd-options.mdx improvements and the enrichments that are required for that.
All other enrichments and improvements to the current docs generator.

That way we can merge 2. in first, and 1. can be left open as a tool for when someone cleans up the CLI documentation.

Right now it feels like a lot is getting added in, and it's not clear to me what's actually beneficial/needed.

temporalcli/commandsgen/enrich.go

temporalcli/internal/cmd/gen-docs/main.go

## 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]>

prasek · 2024-10-30T03:10:51Z

Left some small nit comments, but I'm not sure the split between this PR and #692 is what we want. I think the split we want is:

The cmd-options.mdx improvements and the enrichments that are required for that.

All other enrichments and improvements to the current docs generator.

That way we can merge 2. in first, and 1. can be left open as a tool for when someone cleans up the CLI documentation.

Right now it feels like a lot is getting added in, and it's not clear to me what's actually beneficial/needed.

Makes sense. Removed the cmd-options.mdx improvements and rendered inline options under each command, without cluttering up the right side nav. Also added the mdx acorn rendering fix.

prasek · 2024-10-30T04:18:11Z

Addressed all feedback and think we're good to go.

temporalcli/commandsgen/parse.go

cretz

LGTM (any concerns about approach of pre-populating derivable values are non-blocking). May want to have another reviewer like @josh-berry also look before merging.

josh-berry

I just looked at the output, not the code, and left comments based on what I saw in the generated docs. Thanks again @prasek for working on this!

Also, apologies for the delay in getting to this review. It's been in my list since you first opened the PR, and I usually try to get to them faster than this but I've been a bit scatterbrained.

temporalcli/commandsgen/docs.go

prasek · 2024-10-31T02:03:07Z

Thanks @josh-berry, incorporated all your suggestions on options rendering. Kept the short name for command heading since it's also used to render the right side nav which gets cluttered if using the full name, see above.

prasek · 2024-10-31T03:46:07Z

Addressed feedback on using derived state to keep the model small. Think this is good to go.

josh-berry

This is a definite improvement over what we have today. Thanks @prasek for helping out here! LMK if you need me to merge on your behalf (I forget if you have permission to push the button or not, and I always prefer to let the author do the honors :D ).

josh-berry · 2024-10-31T21:31:36Z

@yuandrew Have all of your comments been addressed and are you comfortable with this being merged? If so can you give an approving review? (GitHub won't dismiss your "requesting changes" review unless you supersede it with an approval.)

yuandrew

sorry, I've been out sick the last two days, changes look good! One minor comment, but looks great otherwise! Thanks for the improvement here Phil :)

temporalcli/commandsgen/docs.go

Signed-off-by: Phil Prasek <[email protected]>

prasek · 2024-11-01T17:19:52Z

addressed @yuandrew's feedback and rebased, so @josh-berry think this is good to merge.

prasek requested a review from yuandrew October 15, 2024 19:32

This was referenced Oct 15, 2024

Enhanced docs gen to more closely match existing docs (legacy) #692

Draft

Update nexus commands.yml for docs gen #693

Merged

prasek changed the title ~~enriched docs gen model~~ Enriched docs gen model Oct 15, 2024

yuandrew requested changes Oct 15, 2024

View reviewed changes

cretz reviewed Oct 16, 2024

View reviewed changes

temporalcli/internal/cmd/gen-docs/main.go Outdated Show resolved Hide resolved

prasek force-pushed the cli-docs-gen-model branch from e399ecf to 309bf35 Compare October 30, 2024 02:51

prasek requested review from cretz and yuandrew October 30, 2024 04:18

prasek changed the title ~~Enriched docs gen model~~ Improved docs gen Oct 30, 2024

cretz reviewed Oct 30, 2024

View reviewed changes

temporalcli/commandsgen/parse.go Show resolved Hide resolved

temporalcli/commandsgen/parse.go Outdated Show resolved Hide resolved

temporalcli/commandsgen/parse.go Outdated Show resolved Hide resolved

cretz approved these changes Oct 30, 2024

View reviewed changes

prasek requested a review from josh-berry October 30, 2024 19:58

josh-berry reviewed Oct 30, 2024

View reviewed changes

prasek requested review from josh-berry and cretz October 31, 2024 03:48

josh-berry approved these changes Oct 31, 2024

View reviewed changes

yuandrew approved these changes Nov 1, 2024

View reviewed changes

temporalcli/commandsgen/docs.go Show resolved Hide resolved

prasek added 5 commits November 1, 2024 10:15

enriched docs gen model

7011cd9

Signed-off-by: Phil Prasek <[email protected]>

address feedback

0ea8ba2

Signed-off-by: Phil Prasek <[email protected]>

move command enrichments to parse.go

af506a3

Signed-off-by: Phil Prasek <[email protected]>

remove cmd-options.mdx enhancements and render cleaner inline options

039ccce

Signed-off-by: Phil Prasek <[email protected]>

address feedback and add experimental option rendering

2eae599

Signed-off-by: Phil Prasek <[email protected]>

prasek added 3 commits November 1, 2024 10:15

address feedback on options rendering

ff043de

Signed-off-by: Phil Prasek <[email protected]>

address feedback to use derieved state to keep the model small

6000ed7

Signed-off-by: Phil Prasek <[email protected]>

emit type once for all forms of an option

1cab984

Signed-off-by: Phil Prasek <[email protected]>

prasek force-pushed the cli-docs-gen-model branch from bf009ca to 1cab984 Compare November 1, 2024 17:16

yuandrew merged commit 100b8fb into temporalio:main Nov 1, 2024
7 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improved docs gen #691

Improved docs gen #691

prasek commented Oct 15, 2024 •

edited

Loading

CLAassistant commented Oct 15, 2024 •

edited

Loading

yuandrew left a comment

prasek commented Oct 30, 2024 •

edited

Loading

prasek commented Oct 30, 2024

cretz left a comment •

edited

Loading

josh-berry left a comment •

edited

Loading

prasek commented Oct 31, 2024 •

edited

Loading

prasek commented Oct 31, 2024 •

edited

Loading

josh-berry left a comment

josh-berry commented Oct 31, 2024

yuandrew left a comment

prasek commented Nov 1, 2024

Improved docs gen #691

Improved docs gen #691

Conversation

prasek commented Oct 15, 2024 • edited Loading

What was changed

Why?

Checklist

CLAassistant commented Oct 15, 2024 • edited Loading

yuandrew left a comment

Choose a reason for hiding this comment

prasek commented Oct 30, 2024 • edited Loading

prasek commented Oct 30, 2024

cretz left a comment • edited Loading

Choose a reason for hiding this comment

josh-berry left a comment • edited Loading

Choose a reason for hiding this comment

prasek commented Oct 31, 2024 • edited Loading

prasek commented Oct 31, 2024 • edited Loading

josh-berry left a comment

Choose a reason for hiding this comment

josh-berry commented Oct 31, 2024

yuandrew left a comment

Choose a reason for hiding this comment

prasek commented Nov 1, 2024

prasek commented Oct 15, 2024 •

edited

Loading

CLAassistant commented Oct 15, 2024 •

edited

Loading

prasek commented Oct 30, 2024 •

edited

Loading

cretz left a comment •

edited

Loading

josh-berry left a comment •

edited

Loading

prasek commented Oct 31, 2024 •

edited

Loading

prasek commented Oct 31, 2024 •

edited

Loading