docs: update template and fix help (#218)

* chore: clean up after myself

* fix: root path to CLI reference

* fix: flags and docs generation

* fix: misplaced empty line

Author: kai687

internal/docs/docs.go

@@ -34,10 +34,9 @@ type Flag struct {
 
 func newFlag(flag *pflag.Flag) Flag {
 	return Flag{
-		Name:      flag.Name,
-		Shorthand: flag.Shorthand,
-		// Add two spaces before each newline to force a newline in markdown
-		Description: strings.ReplaceAll(flag.Usage, "\n", "  \n"),
+		Name:        flag.Name,
+		Shorthand:   flag.Shorthand,
+		Description: strings.TrimSpace(flag.Usage),
 		Default:     flag.DefValue,
 	}
 }

internal/docs/mdx.go

@@ -4,6 +4,7 @@ import (
 	_ "embed"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"text/template"
 
@@ -12,6 +13,8 @@ import (
 
 const mdxDocsRootSlug = "doc/tools/cli/commands"
 
+var algoliaAPIReferenceLinkRE = regexp.MustCompile(`See: (/doc/api-reference/api-parameters/([^\s)]+))`)
+
 //go:embed mdx.tpl
 var mdxTemplate string
 
@@ -26,6 +29,8 @@ func GenMdxTree(cmd *cobra.Command, dir string) error {
 		"getExamples": func(cmd Command) []Example {
 			return cmd.ExamplesList()
 		},
+		"formatAlgoliaDocLinks": formatAlgoliaDocLinks,
+		"trimTrailingNewlines":  trimTrailingNewlines,
 	}).Parse(mdxTemplate)
 	if err != nil {
 		return err
@@ -48,7 +53,7 @@ func newMdxPage(cmd Command) mdxPage {
 }
 
 func writeMdxPageTree(tpl *template.Template, dir string, page mdxPage) error {
-	filename := filepath.Join(dir, commandOutputDir(page.Command), "index.mdx")
+	filename := filepath.Join(dir, commandOutputFilename(page.Command))
 	if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
 		return err
 	}
@@ -81,8 +86,16 @@ func commandPathParts(cmd Command) []string {
 	return parts[1:]
 }
 
-func commandOutputDir(cmd Command) string {
-	return filepath.Join(commandPathParts(cmd)...)
+func commandOutputFilename(cmd Command) string {
+	parts := commandPathParts(cmd)
+	if len(parts) == 0 {
+		return "index.mdx"
+	}
+
+	last := len(parts) - 1
+	parts[last] += ".mdx"
+
+	return filepath.Join(parts...)
 }
 
 func buildMdxSlug(parts []string) string {
@@ -92,3 +105,12 @@ func buildMdxSlug(parts []string) string {
 
 	return mdxDocsRootSlug + "/" + strings.Join(parts, "/")
 }
+
+func trimTrailingNewlines(s string) string {
+	return strings.TrimRight(s, "\n")
+}
+
+func formatAlgoliaDocLinks(s string) string {
+	s = strings.ReplaceAll(s, "https://www.algolia.com/doc", "/doc")
+	return algoliaAPIReferenceLinkRE.ReplaceAllString(s, "See: [`$2`]($1)")
+}

internal/docs/mdx.tpl

@@ -1,52 +1,45 @@
 ---
-navigation: "cli"
-title: |-
-  {{ .Name }}
-description: |-
-  {{ .Description }}
-slug: {{ .Slug }}
+title: {{ .Name }}
+description: {{ .Description }}
+public: true
 ---
-{{ if .Description }}
-{{ .Description }}
-{{ end }}
-
-## Usage
-
-`{{ .Usage }}`
 
-{{ if .Aliases }}
-## Aliases
-
-{{ range $alias := .Aliases -}}
-- `{{ $alias }}`
-{{ end }}
-{{ end }}
+```txt Usage
+{{ .Usage }}
+```
+{{- if .SubPages }}
 
-{{ if .SubPages }}
-## Subcommands
+## Commands
 
 {{ range $subPage := .SubPages -}}
-- [`{{ $subPage.Name }}`](/{{ $subPage.Slug }}): {{ $subPage.Description }}
-{{ end }}
-{{ end }}
+- [`{{ $subPage.Name }}`](/{{ $subPage.Slug }})
+{{ end -}}
+{{ end -}}
+{{ $examples := getExamples .Command -}}
+{{ if $examples }}
 
-{{ $examples := getExamples .Command }}{{ if $examples }}
 ## Examples
-{{ range $example := $examples }}
-{{ $example.Desc }}
 
-```sh{{ if $example.WebCLICommand }} command="{{$example.WebCLICommand}}"{{ end }}
+{{ range $example := $examples -}}
+{{ if $example.Desc }}{{ $example.Desc }}:
+
+{{ end -}}
+```sh icon=square-terminal
 {{ $example.Code }}
 ```
-{{ end }}
-{{ end }}
-
-{{ range $flagKey, $flagSlice := .Flags -}}
+{{ end -}}
+{{ end -}}
+{{ range $flagKey, $flagSlice := .Flags }}
 {{ if $flagSlice }}
 ## {{ $flagKey }}
 
 {{ range $flag := $flagSlice -}}
-- {{ if $flag.Shorthand }}`-{{ $flag.Shorthand }}`, {{ end }}`--{{ $flag.Name }}`: {{ $flag.Description }}
-{{ end }}
+<ParamField body="{{ if $flag.Shorthand }}-{{ $flag.Shorthand }}, {{ end }}--{{ $flag.Name }}">
+
+{{ formatAlgoliaDocLinks (trimTrailingNewlines $flag.Description) }}
+
+</ParamField>
+
+{{ end -}}
 {{ end }}
-{{ end }}
+{{- end -}}

internal/docs/mdx_integration_test.go

@@ -22,7 +22,7 @@ func TestGenMdxTreeSupportsCurrentCommandTree(t *testing.T) {
 	rootContent := readTestFile(t, filepath.Join(dir, "index.mdx"))
 	require.Contains(t, rootContent, "algolia search MOVIES --query \"toy story\"")
 
-	logoutContent := readTestFile(t, filepath.Join(dir, "auth", "logout", "index.mdx"))
+	logoutContent := readTestFile(t, filepath.Join(dir, "auth", "logout.mdx"))
 	require.Contains(t, logoutContent, "algolia auth logout")
 }
 

internal/docs/mdx_test.go

@@ -61,17 +61,16 @@ func TestGenMdxTreeWritesNestedCommandPages(t *testing.T) {
 	require.NoError(t, GenMdxTree(root, dir))
 
 	rootContent := readTestFile(t, filepath.Join(dir, "index.mdx"))
-	require.Contains(t, rootContent, "slug: doc/tools/cli/commands")
+	require.Contains(t, rootContent, "public: true")
 	require.Contains(t, rootContent, "[`algolia events`](/doc/tools/cli/commands/events)")
 
-	eventsContent := readTestFile(t, filepath.Join(dir, "events", "index.mdx"))
-	require.Contains(t, eventsContent, "slug: doc/tools/cli/commands/events")
+	eventsContent := readTestFile(t, filepath.Join(dir, "events.mdx"))
+	require.Contains(t, eventsContent, "public: true")
 	require.Contains(t, eventsContent, "[`algolia events sources`](/doc/tools/cli/commands/events/sources)")
 
-	listContent := readTestFile(t, filepath.Join(dir, "events", "sources", "list", "index.mdx"))
-	require.Contains(t, listContent, "slug: doc/tools/cli/commands/events/sources/list")
-	require.Contains(t, listContent, "`algolia events sources list [flags]`")
-	require.Contains(t, listContent, "`-F`, `--format`")
+	listContent := readTestFile(t, filepath.Join(dir, "events", "sources", "list.mdx"))
+	require.Contains(t, listContent, "algolia events sources list [flags]")
+	require.Contains(t, listContent, `<ParamField body="-F, --format">`)
 }
 
 func TestGenMdxTreeSupportsCodeOnlyExamples(t *testing.T) {