From c602a3bab89d0de69a68e7f12ebaed7427890325 Mon Sep 17 00:00:00 2001 From: Gianluca Arbezzano Date: Fri, 20 Feb 2026 15:26:01 +0100 Subject: [PATCH] feat: remove double title in docs and hide from sidebar We want to hide the majority of the generated commands from sidebar to avoid having too many items in there. This PR does that. It also replaces the name of the datumctl doc with CLI reference since it is the entrypoint for the cli reference. --- docs/index.md | 61 ++++++++++--------- go.sum | 2 - .../cmd/docs/generate-cli-documentation.go | 44 ++++++++++++- .../docs/generate-cli-documentation_test.go | 28 ++++++++- 4 files changed, 101 insertions(+), 34 deletions(-) diff --git a/docs/index.md b/docs/index.md index 888c329..5e759b8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ Let's start installing the binary itself, but if you want to get deeper, make a contribution or you are a curious developer nativate to the [documentation we wrote specifically for you.](developer/overview) -## Homebrew (macOS) +## Homebrew (macOS) (recommended) If you are using macOS and have [Homebrew](https://brew.sh/) installed, you can install `datumctl` via our official tap: @@ -27,35 +27,7 @@ brew install datumctl brew upgrade datumctl ``` -## nix (Linux and macOS) - -datumctl ships with a `flake.nix` so you don't have to install anything: - -``` -# Pick latest from git -nix run github:datum-cloud/datumctl - -# Specify version -nix run github:datum-cloud/datumctl/b044455d877b800812e4fd78e42429c1617c011b - -# Run from local git clone -nix run - -# Start shell with all dependencies available -nix develop --command zsh - -# Build locally -nix build - -# ...or for specific platform -nix build .#packages.x86_64-linux.default -nix build .#packages.aarch64-linux.default -``` - -You can, however, incorporate it into your home-manager build or other -flake so that it's always available in your profile. - -## Pre-built binaries (recommended) +## Pre-built binaries The easiest way to install `datumctl` is by downloading the pre-built binary for your operating system and architecture from the @@ -94,6 +66,35 @@ sudo mv datumctl /usr/local/bin/ > The `sudo mv` command might require administrator privileges. Adjust the > destination path `/usr/local/bin/` if needed for your system. +## nix (Linux and macOS) + +datumctl ships with a `flake.nix` so you don't have to install anything: + +``` +# Pick latest from git +nix run github:datum-cloud/datumctl + +# Specify version +nix run github:datum-cloud/datumctl/b044455d877b800812e4fd78e42429c1617c011b + +# Run from local git clone +nix run + +# Start shell with all dependencies available +nix develop --command zsh + +# Build locally +nix build + +# ...or for specific platform +nix build .#packages.x86_64-linux.default +nix build .#packages.aarch64-linux.default +``` + +You can, however, incorporate it into your home-manager build or other +flake so that it's always available in your profile. + + ## Building from source If you prefer, you can build `datumctl` from source: diff --git a/go.sum b/go.sum index f62a67d..993af73 100644 --- a/go.sum +++ b/go.sum @@ -222,8 +222,6 @@ golang.org/x/mod v0.31.0 h1:HaW9xtz0+kOcWKwli0ZXy79Ix+UW/vOfmWI5QVd2tgI= golang.org/x/mod v0.31.0/go.mod h1:43JraMp9cGx1Rx3AqioxrbrhNsLl2l/iNAvuBkrezpg= golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o= golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8= -golang.org/x/oauth2 v0.34.0 h1:hqK/t4AKgbqWkdkcAeI8XLmbK+4m4G5YeQRrmiotGlw= -golang.org/x/oauth2 v0.34.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA= golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ= golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA= golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4= diff --git a/internal/cmd/docs/generate-cli-documentation.go b/internal/cmd/docs/generate-cli-documentation.go index 827c9aa..e3ddc01 100644 --- a/internal/cmd/docs/generate-cli-documentation.go +++ b/internal/cmd/docs/generate-cli-documentation.go @@ -34,6 +34,8 @@ func GenerateDocumentationCmd(root *cobra.Command) *cobra.Command { ) const fmTemplate = `--- title: "%s" +sidebar: + hidden: true --- ` @@ -44,7 +46,7 @@ title: "%s" } linkHandler := func(name string) string { base := strings.TrimSuffix(name, path.Ext(name)) - return "/docs/datumctl/commands/" + strings.ToLower(base) + "/" + return "/docs/datumctl/command/" + strings.ToLower(base) + "/" } cmd := &cobra.Command{ Use: "generate-cli-docs", @@ -75,6 +77,7 @@ func downscaleMarkdownHeadersInDir(root string) error { } func downscaleMarkdownHeadersInFile(filename string) error { + isDatumctlDoc := filepath.Base(filename) == "datumctl.md" in, err := os.Open(filename) if err != nil { return err @@ -94,6 +97,7 @@ func downscaleMarkdownHeadersInFile(filename string) error { writer := bufio.NewWriter(tmp) inFence := false var fenceMarker string + dropNextH2Header := true for { line, err := reader.ReadString('\n') @@ -114,8 +118,23 @@ func downscaleMarkdownHeadersInFile(filename string) error { fenceMarker = "" } } else if !inFence { + if isDatumctlDoc { + line = replaceDatumctlTitle(line) + } + if dropNextH2Header { + var dropped bool + line, dropped = dropFirstH2HeaderLine(line) + if dropped { + dropNextH2Header = false + if isEOF { + break + } + continue + } + } line = replaceH1WithH3(line) line = normalizeSeeAlsoLine(line) + line = normalizeDatumctlCommandLinks(line) } if _, werr := writer.WriteString(line); werr != nil { @@ -139,6 +158,14 @@ func downscaleMarkdownHeadersInFile(filename string) error { return os.Rename(tmp.Name(), filename) } +func dropFirstH2HeaderLine(line string) (string, bool) { + trimmed := strings.TrimLeft(line, " \t") + if strings.HasPrefix(trimmed, "## ") { + return "", true + } + return line, false +} + func replaceH1WithH3(line string) string { trimmed := strings.TrimLeft(line, " \t") if len(trimmed) == 0 || trimmed[0] != '#' { @@ -171,3 +198,18 @@ func normalizeSeeAlsoLine(line string) string { } return line } + +func normalizeDatumctlCommandLinks(line string) string { + return strings.ReplaceAll(line, "/docs/datumctl/command/datumctl/", "/docs/datumctl/cli-reference/") +} + +func replaceDatumctlTitle(line string) string { + trimmed := strings.TrimSpace(line) + if trimmed == "hidden: true" { + return strings.Replace(line, "hidden: true", "hidden: false", 1) + } + if trimmed == `title: "datumctl"` { + return strings.Replace(line, `title: "datumctl"`, `title: "CLI command reference"`, 1) + } + return line +} diff --git a/internal/cmd/docs/generate-cli-documentation_test.go b/internal/cmd/docs/generate-cli-documentation_test.go index 1c28606..30b5005 100644 --- a/internal/cmd/docs/generate-cli-documentation_test.go +++ b/internal/cmd/docs/generate-cli-documentation_test.go @@ -58,6 +58,33 @@ func TestNormalizeSeeAlsoLine(t *testing.T) { } } +func TestDropFirstH2HeaderLine(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + in string + want string + dropped bool + }{ + {name: "h2 header dropped", in: "## Title\n", want: "", dropped: true}, + {name: "h2 with indent dropped", in: " ## Title\n", want: "", dropped: true}, + {name: "h3 not dropped", in: "### Title\n", want: "### Title\n", dropped: false}, + {name: "non-header", in: "Title\n", want: "Title\n", dropped: false}, + } + + for _, test := range tests { + test := test + t.Run(test.name, func(t *testing.T) { + t.Parallel() + got, dropped := dropFirstH2HeaderLine(test.in) + if got != test.want || dropped != test.dropped { + t.Fatalf("dropFirstH2HeaderLine(%q) = (%q, %v), want (%q, %v)", test.in, got, dropped, test.want, test.dropped) + } + }) + } +} + func TestDownscaleMarkdownHeadersInFile_RespectsFences(t *testing.T) { t.Parallel() @@ -93,7 +120,6 @@ func TestDownscaleMarkdownHeadersInFile_RespectsFences(t *testing.T) { "```bash\n" + "# Not\n" + "```\n" + - "## B\n" + "~~~\n" + "### Not2\n" + "~~~\n"