From f1846804aef7f1f2cafcc2c19bc68ac6d6092387 Mon Sep 17 00:00:00 2001 From: NgThachThanh Date: Tue, 12 May 2026 13:47:22 +0700 Subject: [PATCH 1/2] docs: generate environment variables reference --- cmd/gen-docs/main_test.go | 13 ++++++++ internal/commandsgen/docs.go | 61 ++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) diff --git a/cmd/gen-docs/main_test.go b/cmd/gen-docs/main_test.go index cdd68945c..ab2af4cc2 100644 --- a/cmd/gen-docs/main_test.go +++ b/cmd/gen-docs/main_test.go @@ -3,6 +3,7 @@ package main import ( "os" "path/filepath" + "strings" "testing" ) @@ -36,4 +37,16 @@ func TestGenDocsMultipleInputs(t *testing.T) { if _, err := os.Stat(workflowPath); os.IsNotExist(err) { t.Fatal("workflow.mdx was not generated") } + + envVarsPath := filepath.Join(outputDir, "environment-variables.mdx") + envVars, err := os.ReadFile(envVarsPath) + if os.IsNotExist(err) { + t.Fatal("environment-variables.mdx was not generated") + } + if err != nil { + t.Fatalf("failed reading environment-variables.mdx: %v", err) + } + if !strings.Contains(string(envVars), "`TEMPORAL_ADDRESS`") { + t.Fatal("environment-variables.mdx does not include TEMPORAL_ADDRESS") + } } diff --git a/internal/commandsgen/docs.go b/internal/commandsgen/docs.go index b3857503e..d2fd003b3 100644 --- a/internal/commandsgen/docs.go +++ b/internal/commandsgen/docs.go @@ -30,6 +30,7 @@ func GenerateDocsFiles(commands Commands) (map[string][]byte, error) { // Write global flags section once at the end of each file w.writeGlobalFlagsSections() + w.writeEnvironmentVariablesPage(commands) // Format and return var finalMap = make(map[string][]byte) @@ -224,6 +225,66 @@ func (w *docWriter) writeGlobalFlagsSections() { } } +func (w *docWriter) writeEnvironmentVariablesPage(commands Commands) { + envOptions := make(map[string]Option) + for _, optionSet := range commands.OptionSets { + for _, o := range optionSet.Options { + if o.ImpliedEnv != "" && !o.Hidden { + envOptions[o.ImpliedEnv] = o + } + } + } + for _, command := range commands.CommandList { + for _, o := range command.Options { + if o.ImpliedEnv != "" && !o.Hidden { + envOptions[o.ImpliedEnv] = o + } + } + } + + envNames := make([]string, 0, len(envOptions)) + for envName := range envOptions { + envNames = append(envNames, envName) + } + sort.Strings(envNames) + + buf := &bytes.Buffer{} + buf.WriteString("---\n") + buf.WriteString("id: environment-variables\n") + buf.WriteString("title: Temporal CLI environment variables\n") + buf.WriteString("sidebar_label: Environment variables\n") + buf.WriteString("description: Reference for Temporal CLI environment variables.\n") + buf.WriteString("toc_max_heading_level: 4\n") + buf.WriteString("keywords:\n") + buf.WriteString(" - cli\n") + buf.WriteString(" - environment variables\n") + buf.WriteString(" - temporal cli\n") + buf.WriteString("tags:\n") + buf.WriteString(" - Temporal CLI\n") + buf.WriteString("---\n\n") + buf.WriteString("{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten.\n") + buf.WriteString("This file is generated from https://github.com/temporalio/cli/blob/main/internal/commandsgen/commands.yml via internal/cmd/gen-docs */}\n\n") + buf.WriteString("This page lists the environment variables that can configure the Temporal CLI.\n\n") + buf.WriteString("| Variable | Flag | Description | Default |\n") + buf.WriteString("|----------|------|-------------|---------|\n") + + for _, envName := range envNames { + o := envOptions[envName] + flagName := fmt.Sprintf("`--%s`", o.Name) + description := encodeJSONExample(o.Description) + description = strings.ReplaceAll(description, "\n", "
") + description = strings.ReplaceAll(description, "|", "\\|") + defaultVal := "" + if o.Default != "" { + defaultVal = fmt.Sprintf("`%s`", o.Default) + } + buf.WriteString(fmt.Sprintf("| `%s` | %s | %s | %s |\n", envName, flagName, description, defaultVal)) + } + buf.WriteString("\n") + + w.fileMap["environment-variables"] = buf +} + 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, " ")) { From 005a14fbb4a4c30320f8566d28daef7e3bfd4815 Mon Sep 17 00:00:00 2001 From: NgThachThanh Date: Tue, 12 May 2026 13:56:46 +0700 Subject: [PATCH 2/2] docs: fix generated docs source note --- internal/commandsgen/docs.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/internal/commandsgen/docs.go b/internal/commandsgen/docs.go index d2fd003b3..0031f9e4e 100644 --- a/internal/commandsgen/docs.go +++ b/internal/commandsgen/docs.go @@ -82,7 +82,7 @@ func (w *docWriter) writeCommand(c *Command) { w.fileMap[fileName].WriteString("---") w.fileMap[fileName].WriteString("\n\n") w.fileMap[fileName].WriteString("{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten.\n") - w.fileMap[fileName].WriteString("This file is generated from https://github.com/temporalio/cli/blob/main/internal/commandsgen/commands.yml via internal/cmd/gen-docs */}\n\n") + w.fileMap[fileName].WriteString("This file is generated from https://github.com/temporalio/cli/blob/main/internal/temporalcli/commands.yaml and https://github.com/temporalio/cli/blob/main/cliext/option-sets.yaml via cmd/gen-docs */}\n\n") // Add introductory paragraph w.fileMap[fileName].WriteString(fmt.Sprintf("This page provides a reference for the `temporal` CLI `%s` command. ", fileName)) w.fileMap[fileName].WriteString("The flags applicable to each subcommand are presented in a table within the heading for the subcommand. ") @@ -263,7 +263,7 @@ func (w *docWriter) writeEnvironmentVariablesPage(commands Commands) { buf.WriteString(" - Temporal CLI\n") buf.WriteString("---\n\n") buf.WriteString("{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten.\n") - buf.WriteString("This file is generated from https://github.com/temporalio/cli/blob/main/internal/commandsgen/commands.yml via internal/cmd/gen-docs */}\n\n") + buf.WriteString("This file is generated from https://github.com/temporalio/cli/blob/main/internal/temporalcli/commands.yaml and https://github.com/temporalio/cli/blob/main/cliext/option-sets.yaml via cmd/gen-docs */}\n\n") buf.WriteString("This page lists the environment variables that can configure the Temporal CLI.\n\n") buf.WriteString("| Variable | Flag | Description | Default |\n") buf.WriteString("|----------|------|-------------|---------|\n")