docs: add prepare script to generate sidebar (#11894)

www/packages/build-scripts/package.json

@@ -28,8 +28,10 @@
     "watch": "tsc --watch"
   },
   "dependencies": {
+    "@readme/openapi-parser": "^3.0.1",
     "docs-utils": "*",
     "fdir": "^6.4.3",
+    "pluralize": "^8.0.0",
     "slugify": "^1.6.6",
     "tags": "*",
     "yaml": "^2.7.0"

www/packages/build-scripts/src/generate-sidebar.ts

@@ -7,6 +7,7 @@ import numberSidebarItems from "./utils/number-sidebar-items.js"
 import { sortSidebarItems } from "./utils/sidebar-sorting.js"
 import { Sidebar } from "types"
 import { validateSidebarUniqueIds } from "./utils/validate-sidebar-unique-ids.js"
+import getApiRefSidebarChildren from "./utils/get-api-ref-sidebar-children.js"
 
 export type ItemsToAdd = Sidebar.SidebarItem & {
   sidebar_position?: number
@@ -17,8 +18,12 @@ export type GenerateSidebarOptions = {
   writeToFile?: boolean
 }
 
-const customGenerators: Record<string, () => Promise<ItemsToAdd[]>> = {
+const customGenerators: Record<
+  string,
+  (sidebar?: Sidebar.RawSidebar) => Promise<ItemsToAdd[]>
+> = {
   "core-flows": getCoreFlowsRefSidebarChildren,
+  "api-ref": getApiRefSidebarChildren,
 }
 
 function sortItems(itemA: ItemsToAdd, itemB: ItemsToAdd): number {
@@ -241,9 +246,14 @@ export async function generateSidebar(
   validateSidebarUniqueIds(sidebars)
 
   for (const sidebarItem of sidebars) {
+    const hasCustomAutogenerator =
+      sidebarItem.custom_autogenerate &&
+      Object.hasOwn(customGenerators, sidebarItem.custom_autogenerate)
     normalizedSidebars.push({
       ...sidebarItem,
-      items: await checkItems(sidebarItem.items, restOptions),
+      items: !hasCustomAutogenerator
+        ? await checkItems(sidebarItem.items, restOptions)
+        : await customGenerators[sidebarItem.custom_autogenerate!](sidebarItem),
     })
   }
 

www/packages/build-scripts/src/utils/get-api-ref-sidebar-children.ts

@@ -0,0 +1,85 @@
+import { OpenAPI, Sidebar } from "types"
+import { ItemsToAdd } from "../index.js"
+import path from "path"
+import { findAllPageHeadings, getSectionId } from "docs-utils"
+import { readFile } from "fs/promises"
+import { parse } from "@readme/openapi-parser"
+import pkg from "pluralize"
+
+const { singular } = pkg
+
+export default async function getApiRefSidebarChildren(
+  sidebar?: Sidebar.RawSidebar
+): Promise<ItemsToAdd[]> {
+  if (!sidebar) {
+    return []
+  }
+
+  const projPath = path.resolve()
+  const area = sidebar.sidebar_id
+  const items: ItemsToAdd[] = [
+    {
+      type: "link",
+      title: "Introduction",
+      path: "introduction",
+      loaded: true,
+    },
+  ]
+
+  // get sidebar items from markdown files
+  const markdownPath = path.join(projPath, "markdown", `${area}.mdx`)
+  const headings = findAllPageHeadings({
+    content: await readFile(markdownPath, "utf-8"),
+    level: 2,
+  })
+
+  headings.forEach((heading) => {
+    items.push({
+      type: "link",
+      title: heading,
+      path: getSectionId([heading]),
+      loaded: true,
+    })
+  })
+
+  // read base specs
+  const baseSpecs = (await parse(
+    path.join(projPath, "specs", area, "openapi.yaml")
+  )) as OpenAPI.ExpandedDocument
+
+  if (baseSpecs.tags?.length) {
+    items.push({
+      type: "separator",
+    })
+  }
+
+  // add tags to sidebar
+  baseSpecs.tags?.forEach((tag: OpenAPI.TagObject) => {
+    const item: ItemsToAdd = {
+      type: "category",
+      title: tag.name,
+      children: [],
+      loaded: false,
+      showLoadingIfEmpty: true,
+    }
+
+    if (tag["x-associatedSchema"]) {
+      const formattedName = singular(tag.name).replaceAll(" ", "")
+      const schemaSlug = getSectionId([tag.name, formattedName, "schema"])
+      item.children!.push({
+        type: "link",
+        path: schemaSlug,
+        title: `${formattedName} Object`,
+        loaded: true,
+        badge: {
+          variant: "neutral",
+          text: "Schema",
+        },
+      })
+    }
+
+    items.push(item)
+  })
+
+  return items
+}