Autogenerate code to conform to current docs structure (#1505)

confluentinc · Nov 10, 2022 · 5fd0420 · 5fd0420
1 parent 51e5f7f
commit 5fd0420
Show file tree

Hide file tree

Showing 3 changed files with 44 additions and 24 deletions.
diff --git a/internal/pkg/docs/doc_page.go b/internal/pkg/docs/doc_page.go
@@ -27,7 +27,7 @@ func printDocPage(tabs []Tab, depth int) []string {
 	cmd := tabs[0].Command
 
 	return flatten([][]string{
-		printHeader(cmd),
+		printHeader(cmd, false),
 		printTitle(cmd, "-"),
 		printWarnings(cmd, depth),
 		printTabbedSection("Description", printDescriptionAndUsage, tabs),

diff --git a/internal/pkg/docs/index_page.go b/internal/pkg/docs/index_page.go
@@ -20,40 +20,47 @@ const tab = "   "
 // generateIndexPage creates a file called index.rst which contains the command description and links to subcommands.
 // If there are multiple versions of a single command, tabs are used within index.rst.
 func generateIndexPage(tabs []Tab, dir string) error {
-	rows := printIndexPage(tabs)
-
 	if cmd := tabs[0].Command; cmd == cmd.Root() {
+		rows := printIndexPage(tabs, true)
 		if err := writeFile(filepath.Join(dir, "overview.rst"), strings.Join(rows, "\n")); err != nil {
 			return err
 		}
 
 		rows = printRootIndexPage(tabs)
+		return writeFile(filepath.Join(dir, "index.rst"), strings.Join(rows, "\n"))
 	}
 
+	rows := printIndexPage(tabs, false)
 	return writeFile(filepath.Join(dir, "index.rst"), strings.Join(rows, "\n"))
 }
 
-func printIndexPage(tabs []Tab) []string {
+func printRootIndexPage(tabs []Tab) []string {
 	cmd := tabs[0].Command
 
 	return flatten([][]string{
-		printHeader(cmd),
+		printHeader(cmd, false),
 		printTitle(cmd, "="),
-		printTabbedSection("Description", printDescription, tabs),
+		printInlineScript(),
 		printTableOfContents(tabs),
-		printTabbedSection("Subcommands", printSubcommands, tabs),
 	})
 }
 
-func printRootIndexPage(tabs []Tab) []string {
+func printIndexPage(tabs []Tab, isOverview bool) []string {
 	cmd := tabs[0].Command
 
-	return flatten([][]string{
-		printHeader(cmd),
+	rows := [][]string{
+		printHeader(cmd, isOverview),
 		printTitle(cmd, "="),
-		printInlineScript(),
-		printTableOfContents(tabs),
-	})
+		printTabbedSection("Description", printDescription, tabs),
+	}
+
+	if cmd := tabs[0].Command; cmd != cmd.Root() {
+		rows = append(rows, printTableOfContents(tabs))
+	}
+
+	rows = append(rows, printTabbedSection("Subcommands", printSubcommands, tabs))
+
+	return flatten(rows)
 }
 
 func flatten(arrs [][]string) []string {
@@ -64,9 +71,9 @@ func flatten(arrs [][]string) []string {
 	return flatArr
 }
 
-func printHeader(cmd *cobra.Command) []string {
+func printHeader(cmd *cobra.Command, isOverview bool) []string {
 	return []string{
-		fmt.Sprintf(".. _%s:", printRef(cmd)),
+		fmt.Sprintf(".. _%s:", printRef(cmd, isOverview)),
 		"",
 	}
 }
@@ -115,10 +122,14 @@ func printTableOfContents(tabs []Tab) []string {
 
 	rows := []string{
 		".. toctree::",
-		tab + ":hidden:",
-		"",
 	}
 
+	if cmd := tabs[0].Command; cmd == cmd.Root() {
+		rows = append(rows, tab+":maxdepth: 1")
+	}
+
+	rows = append(rows, tab+":hidden:", "")
+
 	if cmd := tabs[0].Command; cmd == cmd.Root() {
 		rows = append(rows, tab+"Overview <overview>")
 	}
@@ -135,7 +146,7 @@ func printLink(cmd *cobra.Command) string {
 		// Example: command/index
 		return path.Join(cmd.Name(), "index")
 	} else {
-		return printRef(cmd)
+		return printRef(cmd, false)
 	}
 }
 
@@ -208,17 +219,20 @@ func printSubcommands(cmd *cobra.Command) ([]string, bool) {
 }
 
 func printSphinxRef(cmd *cobra.Command) string {
-	ref := printRef(cmd)
+	ref := printRef(cmd, false)
 	return fmt.Sprintf(":ref:`%s`", ref)
 }
 
-func printRef(cmd *cobra.Command) string {
+func printRef(cmd *cobra.Command, isOverview bool) string {
 	// Example: command_subcommand
 	ref := strings.ReplaceAll(cmd.CommandPath(), " ", "_")
 
 	// The root ref is named "confluent-ref"
 	if cmd == cmd.Root() {
 		ref += "-ref"
+		if isOverview {
+			ref += "-index"
+		}
 	}
 
 	return ref

diff --git a/internal/pkg/docs/index_page_test.go b/internal/pkg/docs/index_page_test.go
@@ -74,7 +74,7 @@ func TestPrintIndexPage(t *testing.T) {
 		"      ",
 	}
 
-	require.Equal(t, expected, printIndexPage(tabs))
+	require.Equal(t, expected, printIndexPage(tabs, false))
 }
 
 func TestPrintRootIndexPage(t *testing.T) {
@@ -134,7 +134,7 @@ func TestPrintHeader(t *testing.T) {
 		"",
 	}
 
-	require.Equal(t, expected, printHeader(cmd))
+	require.Equal(t, expected, printHeader(cmd, false))
 }
 
 func TestPrintTitle_Root(t *testing.T) {
@@ -194,6 +194,7 @@ func TestPrintTableOfContents(t *testing.T) {
 
 	expected := []string{
 		".. toctree::",
+		"   :maxdepth: 1",
 		"   :hidden:",
 		"",
 		"   Overview <overview>",
@@ -267,7 +268,12 @@ func TestPrintSphinxRef(t *testing.T) {
 
 func TestPrintRef_Root(t *testing.T) {
 	cmd := &cobra.Command{Use: "command"}
-	require.Equal(t, "command-ref", printRef(cmd))
+	require.Equal(t, "command-ref", printRef(cmd, false))
+}
+
+func TestPrintRef_Overview(t *testing.T) {
+	cmd := &cobra.Command{Use: "command"}
+	require.Equal(t, "command-ref-index", printRef(cmd, true))
 }
 
 func TestPrintRef(t *testing.T) {
@@ -276,7 +282,7 @@ func TestPrintRef(t *testing.T) {
 
 	a.AddCommand(b)
 
-	require.Equal(t, "a_b", printRef(b))
+	require.Equal(t, "a_b", printRef(b, false))
 }
 
 func TestDedent(t *testing.T) {