-
Notifications
You must be signed in to change notification settings - Fork 42
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Auto generate CLI docs for documentation repo (#685)
## What was changed Auto generate all of the *.mdx files present in the current documentation repo. index.mdx is not auto-generated IMPORTANT: The generated files are not yet being consumed anywhere. A future PR will auto-publish a PR into the docs repo whenever there is a docs related change. Added a field in the YML to indicate doc-specific information, like SEO related keywords and descriptions. Removed `cmd-options.cdx` and print each command option description inline in each file instead. temporalio/documentation#3122 removes all references to this file from the documentation side. ## Why? This is in a larger effort to have the CLI be the source of truth for docs, and have the documentation auto-ingest any CLI changes, keeping all information in sync. This is the first step to this goal, there are a number of follow up tasks that I wanted to split up from this PR: 1. Diff the current information on the docs with the CLI, and unify into a single master-description for each command. 2. Auto-publish PR to docs repo whenever there is a CLI doc change 1. Auto update sidebars.js and vercel.js whenever a new temporal command is added. 3. Clean up the SEO keywords/tags - being handled by the documentation team 4. Support markdown in the CLI help output in terminal #687 ## Checklist 7. Any docs updates needed? <!--- update README if applicable or point out where to update docs.temporal.io --> For now, docs will not be updated. There will be a future PR that auto-creates a PR into the documentation repo with any updates. --------- Co-authored-by: David Reiss <[email protected]>
- Loading branch information
Showing
5 changed files
with
343 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| package commandsgen | ||
|
|
||
| import ( | ||
| "bytes" | ||
| "fmt" | ||
| "sort" | ||
| "strings" | ||
| ) | ||
|
|
||
| type DocsFile struct { | ||
| FileName string | ||
| } | ||
|
|
||
| func GenerateDocsFiles(commands Commands) (map[string][]byte, error) { | ||
| optionSetMap := make(map[string]OptionSets) | ||
| for i, optionSet := range commands.OptionSets { | ||
| optionSetMap[optionSet.Name] = commands.OptionSets[i] | ||
| } | ||
|
|
||
| w := &docWriter{fileMap: make(map[string]*bytes.Buffer), optionSetMap: optionSetMap} | ||
|
|
||
| // sort by parent command (activity, batch, etc) | ||
| for _, cmd := range commands.CommandList { | ||
| if err := cmd.writeDoc(w); err != nil { | ||
| return nil, fmt.Errorf("failed writing docs for command %s: %w", cmd.FullName, err) | ||
| } | ||
| } | ||
|
|
||
| // Format and return | ||
| var finalMap = make(map[string][]byte) | ||
| for key, buf := range w.fileMap { | ||
| finalMap[key] = buf.Bytes() | ||
| } | ||
| return finalMap, nil | ||
| } | ||
|
|
||
| type docWriter struct { | ||
| fileMap map[string]*bytes.Buffer | ||
| optionSetMap map[string]OptionSets | ||
| optionsStack [][]Option | ||
| } | ||
|
|
||
| func (c *Command) writeDoc(w *docWriter) error { | ||
| commandLength := len(strings.Split(c.FullName, " ")) | ||
| w.processOptions(c) | ||
|
|
||
| // If this is a root command, write a new file | ||
| if commandLength == 2 { | ||
| w.writeCommand(c) | ||
| } else if commandLength > 2 { | ||
| w.writeSubcommand(c) | ||
| } | ||
| return nil | ||
| } | ||
|
|
||
| func (w *docWriter) writeCommand(c *Command) { | ||
| fileName := strings.Split(c.FullName, " ")[1] | ||
| w.fileMap[fileName] = &bytes.Buffer{} | ||
| w.fileMap[fileName].WriteString("---\n") | ||
| w.fileMap[fileName].WriteString("id: " + fileName + "\n") | ||
| w.fileMap[fileName].WriteString("title: " + c.FullName + "\n") | ||
| w.fileMap[fileName].WriteString("sidebar_label: " + c.FullName + "\n") | ||
| w.fileMap[fileName].WriteString("description: " + c.Docs.DescriptionHeader + "\n") | ||
| w.fileMap[fileName].WriteString("toc_max_heading_level: 4\n") | ||
| w.fileMap[fileName].WriteString("keywords:\n") | ||
| for _, keyword := range c.Docs.Keywords { | ||
| w.fileMap[fileName].WriteString(" - " + keyword + "\n") | ||
| } | ||
| // tags are the same as Keywords, but with `-` instead of ` ` | ||
| w.fileMap[fileName].WriteString("tags:\n") | ||
| for _, keyword := range c.Docs.Keywords { | ||
| w.fileMap[fileName].WriteString(" - " + strings.ReplaceAll(keyword, " ", "-") + "\n") | ||
| } | ||
| w.fileMap[fileName].WriteString("---\n\n") | ||
| } | ||
|
|
||
| func (w *docWriter) writeSubcommand(c *Command) { | ||
| fileName := strings.Split(c.FullName, " ")[1] | ||
| subCommand := strings.Join(strings.Split(c.FullName, " ")[2:], "") | ||
| w.fileMap[fileName].WriteString("## " + subCommand + "\n\n") | ||
| w.fileMap[fileName].WriteString(c.Description + "\n\n") | ||
| w.fileMap[fileName].WriteString("Use the following options to change the behavior of this command.\n\n") | ||
|
|
||
| // gather options from command and all options aviailable from parent commands | ||
| var allOptions = make([]Option, 0) | ||
| for _, options := range w.optionsStack { | ||
| allOptions = append(allOptions, options...) | ||
| } | ||
|
|
||
| // alphabetize options | ||
| sort.Slice(allOptions, func(i, j int) bool { | ||
| return allOptions[i].Name < allOptions[j].Name | ||
| }) | ||
|
|
||
| for _, option := range allOptions { | ||
| w.fileMap[fileName].WriteString(fmt.Sprintf("## %s\n\n", option.Name)) | ||
| w.fileMap[fileName].WriteString(option.Description + "\n\n") | ||
|
|
||
| } | ||
| } | ||
|
|
||
| func (w *docWriter) processOptions(c *Command) { | ||
| // Pop options from stack if we are moving up a level | ||
| if len(w.optionsStack) >= len(strings.Split(c.FullName, " ")) { | ||
| w.optionsStack = w.optionsStack[:len(w.optionsStack)-1] | ||
| } | ||
| var options []Option | ||
| options = append(options, c.Options...) | ||
|
|
||
| // Maintain stack of options available from parent commands | ||
| for _, set := range c.OptionSets { | ||
| optionSetOptions := w.optionSetMap[set].Options | ||
| options = append(options, optionSetOptions...) | ||
| } | ||
|
|
||
| w.optionsStack = append(w.optionsStack, options) | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.