From bfe08cde98efc3bcf765573fb4ab8deb7a3a87ed Mon Sep 17 00:00:00 2001 From: Andrew Mason Date: Mon, 17 Jul 2023 09:40:56 -0400 Subject: [PATCH 1/2] fix docgen for subcommands Signed-off-by: Andrew Mason --- go/cmd/internal/docgen/docgen.go | 94 ++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 4 deletions(-) diff --git a/go/cmd/internal/docgen/docgen.go b/go/cmd/internal/docgen/docgen.go index 6fe461e5af7..461c0012dc1 100644 --- a/go/cmd/internal/docgen/docgen.go +++ b/go/cmd/internal/docgen/docgen.go @@ -46,11 +46,14 @@ import ( "fmt" "io/fs" "os" + "os/exec" "path/filepath" "strings" "github.com/spf13/cobra" "github.com/spf13/cobra/doc" + + "vitess.io/vitess/go/vt/log" ) // GenerateMarkdownTree generates a markdown doctree for the root cobra.Command @@ -79,9 +82,89 @@ func GenerateMarkdownTree(cmd *cobra.Command, dir string) error { return fmt.Errorf("failed to index doc (generated at %s) into proper position (%s): %w", rootDocPath, indexDocPath, err) } + if err := restructure(dir, dir, cmd.Name(), cmd.Commands()); err != nil { + return err + } + + return nil +} + +/* +_index.md (aka vtctldclient.md) +vtctldclient_AddCellInfo.md +vtctldclient_movetables.md +vtctldclient_movetables_show.md + +becomes + +_index.md +vtctldclient_AddCellInfo.md +vtctldclient_movetables/ + _index.md + vtctldclient_movetables_show.md +*/ + +func restructure(rootDir string, dir string, name string, commands []*cobra.Command) error { + for _, cmd := range commands { + fullCmdFilename := strings.Join([]string{name, cmd.Name()}, "_") + + children := cmd.Commands() + + switch { + case len(children) > 0: + // Command (top-level or not) with children. + // 1. Set up a directory for its children. + // 2. Move its doc into that dir as "_index.md" + // 3. Restructure its children. + cmdDir := filepath.Join(dir, fullCmdFilename) + if err := os.MkdirAll(cmdDir, 0755); err != nil { + return fmt.Errorf("failed to create subdir for %s: %w", fullCmdFilename, err) + } + + if err := os.Rename(filepath.Join(rootDir, fullCmdFilename+".md"), filepath.Join(cmdDir, "_index.md")); err != nil { + return fmt.Errorf("failed to move index doc for command %s with children: %w", fullCmdFilename, err) + } + + if err := restructure(rootDir, cmdDir, fullCmdFilename, children); err != nil { + return fmt.Errorf("failed to restructure child commands for %s: %w", fullCmdFilename, err) + } + case rootDir != dir: + // Sub-command without children. + // 1. Move its doc into the directory for its parent, name unchanged. + if cmd.Name() == "help" { + // all commands with children have their own "help" subcommand, + // which we do not generate docs for + continue + } + + oldName := filepath.Join(rootDir, fullCmdFilename+".md") + newName := filepath.Join(dir, fullCmdFilename+".md") + + if err := os.Rename(oldName, newName); err != nil { + return fmt.Errorf("failed to move child command %s to its parent's dir: %w", fullCmdFilename, err) + } + + sed := newParentLinkSedCommand(name, newName) + if out, err := sed.CombinedOutput(); err != nil { + return fmt.Errorf("failed to rewrite links to parent command in child %s: %w (extra: %s)", newName, err, out) + } + + if err := os.Remove(newName + ".bak"); err != nil { + log.Warningf("failed to remove backup file for %s, use caution when staging files for commit: %w", newName+".bak", err) + } + default: + // Top-level command without children. Nothing to restructure. + continue + } + } + return nil } +func newParentLinkSedCommand(parent string, file string) *exec.Cmd { + return exec.Command("sed", "-i.bak", "-e", fmt.Sprintf("s:(./%s/):(../):", parent), file) +} + func recursivelyDisableAutoGenTags(root *cobra.Command) { commands := []*cobra.Command{root} for cmd := commands[0]; len(commands) > 0; cmd, commands = commands[0], commands[1:] { @@ -106,16 +189,19 @@ func frontmatterFilePrepender(filename string) string { cmdName = root } + cmdName = strings.ReplaceAll(cmdName, "_", " ") + return fmt.Sprintf(frontmatter, cmdName, root) } func linkHandler(filename string) string { - name := filepath.Base(filename) - base := strings.TrimSuffix(name, filepath.Ext(name)) + base := filepath.Base(filename) + name := strings.TrimSuffix(base, filepath.Ext(base)) - if _, _, ok := strings.Cut(base, "_"); !ok { + _, _, ok := strings.Cut(name, "_") + if !ok { return "../" } - return fmt.Sprintf("./%s/", strings.ToLower(base)) + return fmt.Sprintf("./%s/", strings.ToLower(name)) } From d858b37266c505dca53c9fbcdfaaf677f0b19f74 Mon Sep 17 00:00:00 2001 From: Andrew Mason Date: Mon, 17 Jul 2023 12:09:26 -0400 Subject: [PATCH 2/2] no need to delete backups if you dont take em ;) Signed-off-by: Andrew Mason --- go/cmd/internal/docgen/docgen.go | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/go/cmd/internal/docgen/docgen.go b/go/cmd/internal/docgen/docgen.go index 461c0012dc1..d7c1b45b154 100644 --- a/go/cmd/internal/docgen/docgen.go +++ b/go/cmd/internal/docgen/docgen.go @@ -52,8 +52,6 @@ import ( "github.com/spf13/cobra" "github.com/spf13/cobra/doc" - - "vitess.io/vitess/go/vt/log" ) // GenerateMarkdownTree generates a markdown doctree for the root cobra.Command @@ -148,10 +146,6 @@ func restructure(rootDir string, dir string, name string, commands []*cobra.Comm if out, err := sed.CombinedOutput(); err != nil { return fmt.Errorf("failed to rewrite links to parent command in child %s: %w (extra: %s)", newName, err, out) } - - if err := os.Remove(newName + ".bak"); err != nil { - log.Warningf("failed to remove backup file for %s, use caution when staging files for commit: %w", newName+".bak", err) - } default: // Top-level command without children. Nothing to restructure. continue @@ -162,7 +156,7 @@ func restructure(rootDir string, dir string, name string, commands []*cobra.Comm } func newParentLinkSedCommand(parent string, file string) *exec.Cmd { - return exec.Command("sed", "-i.bak", "-e", fmt.Sprintf("s:(./%s/):(../):", parent), file) + return exec.Command("sed", "-i ''", "-e", fmt.Sprintf("s:(./%s/):(../):", parent), file) } func recursivelyDisableAutoGenTags(root *cobra.Command) {