feat: api navigation reorder (#3841)

* bump fdr-sdk

* stash

* compiles

* remove deadcode

* reorganize

* fix mrlint

* parse

* write a test

* minor fixes

* more path resolution options

* lint:fix

* allow merging subpackages

* fix eslint issue

* move hume into the right location

* declare subpackages based on folder structure

* update tests

* update snapshot

* add debug logging

* use a somewhat easier format

* reconfigure api slightly

* add all supported configurations

* fix idgen

* add more variations

* enumerate

* revert yaml-migrations

* revert

* fixes

packages/cli/configuration/fern/definition/docs.yml

@@ -168,7 +168,7 @@ types:
     union:
       - PageConfiguration
       - SectionConfiguration
-      - ApiSectionConfiguration
+      - ApiReferenceConfiguration
       - LinkConfiguration
 
   LogoConfiguration:
@@ -391,7 +391,7 @@ types:
       hidden: optional<boolean>
       skip-slug: optional<boolean>
 
-  ApiSectionConfiguration:
+  ApiReferenceConfiguration:
     properties:
       api: string
       "api-name":
@@ -404,75 +404,95 @@ types:
       snippets: optional<SnippetsConfiguration>
       summary:
         type: optional<string>
-        docs: |
-          Relative path to the markdown file. This summary is displayed at the top of the API section.
+        docs: Relative path to the markdown file
       layout:
-        type: optional<ApiNavigationItems>
+        type: optional<list<ApiReferenceLayoutItem>>
         docs: |
           Advanced usage: when specified, this object will be used to customize the order that your API endpoints are displayed in the docs site, including subpackages, and additional markdown pages (to be rendered in between API endpoints). If not specified, the order will be inferred from the OpenAPI Spec or Fern Definition.
       icon: optional<string>
       slug: optional<string>
       hidden: optional<boolean>
       skip-slug: optional<boolean>
+      alphabetized:
+        type: optional<boolean>
+        docs: |
+          If `alphabetized` is set to true, packages and endpoints will be sorted alphabetically, unless explicitly ordered in the `layout` object.
       flattened:
         type: optional<boolean>
         docs: |
           If `flattened` is set to true, the title specified in `api` will be hidden, and its endpoints and subpackages won't be grouped under it.
 
           This setting is useful if the API reference is short and you want to display all endpoints at the top level.
+      paginated:
+        availability: in-development
+        type: optional<boolean>
+        docs: If true, the API reference will be paginated rather than displayed in a single page (long-scrolling).
 
-  ApiNavigationItem:
+  ApiReferenceLayoutItem:
     docs: |
       Use the `layout` object to customize the order that your API endpoints
       are displayed in the docs site.
     discriminated: false
     union:
       - type: string
+        docs: This should be either an endpoint, websocket, webhook, or subpackage ID
+      - type: map<string, ApiReferencePackageConfiguration>
+        docs: Keyed by subpackage name, this object allows you to group endpoints and pages together.
+      - ApiReferenceSectionConfiguration
+      - ApiReferenceEndpointConfiguration
+      - PageConfiguration
+      - LinkConfiguration
+
+  ApiReferenceSectionConfiguration:
+    properties:
+      section:
+        type: string
         docs: |
-          This should be either an endpoint, websocket, webhook, or subpackage ID
-      - type: map<string, ApiNavigationItems>
-        docs: |
-          Keyed by subpackage ID, this object allows you to group endpoints and pages together.
-      - type: PageConfiguration
-        docs: |
-          This should be a markdown file that will be displayed in the API section.
-
-  ApiNavigationItems:
-    type: list<ApiNavigationItem>
-    examples:
-      - name: Ordering Groups
-        value:
-          - users # users endpoints will be displayed first
-          - roles
-          - permissions
-      - name: Ordering Endpoints
-        value:
-          - roles:
-              - get
-              - create
-              - update
-          - users:
-              - get
-              - create
-              - update
-          - permissions:
-              - get
-              - create
-              - update
-      - name: Ordering Groups and Pages
-        value:
-          - users
-          - roles:
-              - get
-              - create
-              - ./pages/inner-page.mdx
-              - update
-          - permissions
+          The title of the api package that will be displayed in the sidebar.
+      referenced-packages:
+        type: optional<list<string>>
+        docs: This section will inherit the endpoints from the specified subpackage(s). If multiple packages are specified, they will be merged.
+      summary:
+        type: optional<string>
+        docs: Relative path to the markdown file.
+      contents: optional<list<ApiReferenceLayoutItem>>
+      slug: optional<string>
+      icon: optional<string>
+      hidden: optional<boolean>
+      skip-slug: optional<boolean>
+
+  ApiReferencePackageConfiguration:
+    discriminated: false
+    union:
+      - list<ApiReferenceLayoutItem>
+      - ApiReferencePackageConfigurationWithOptions
+
+  ApiReferencePackageConfigurationWithOptions:
+    properties:
+      title: optional<string>
+      summary:
+        type: optional<string>
+        docs: |
+          Relative path to the markdown file. This summary is displayed at the top of the API section.
+      contents: optional<list<ApiReferenceLayoutItem>>
+      slug: optional<string>
+      icon: optional<string>
+      hidden: optional<boolean>
+      skip-slug: optional<boolean>
+
+  ApiReferenceEndpointConfiguration:
+    properties:
+      endpoint: string
+      title: optional<string>
+      slug: optional<string>
+      icon: optional<string>
+      hidden: optional<boolean>
 
   LinkConfiguration:
     properties:
       link: string
       href: string
+      icon: optional<string>
 
   VersionedSnippetLanguageConfiguration:
     properties:

packages/cli/configuration/package.json

@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.97.0-bec92c652",
+    "@fern-api/fdr-sdk": "0.98.0-rc1",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-fern/fiddle-sdk": "^0.0.552",

packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts

@@ -183,17 +183,20 @@ export declare namespace DocsNavigationItem {
         showErrors: boolean;
         snippetsConfiguration: SnippetsConfiguration | undefined;
         summaryAbsolutePath: AbsoluteFilePath | undefined;
-        navigation: ParsedApiNavigationItem[];
+        navigation: ParsedApiReferenceLayoutItem[];
         hidden: boolean | undefined;
         slug: string | undefined;
         skipUrlSlug: boolean | undefined;
-        flattened: boolean | undefined;
+        alphabetized: boolean;
+        flattened: boolean;
+        paginated: boolean;
     }
 
     export interface Link {
         type: "link";
         text: string;
         url: string;
+        icon: string | undefined;
     }
 
     export interface VersionedSnippetLanguageConfiguration {
@@ -209,12 +212,37 @@ export declare namespace DocsNavigationItem {
     }
 }
 
-export declare namespace ParsedApiNavigationItem {
-    export interface Subpackage {
-        type: "subpackage";
-        subpackageId: string;
+export declare namespace ParsedApiReferenceLayoutItem {
+    export interface Section {
+        type: "section";
+        title: string; // title
+        referencedSubpackages: string[]; // subpackage IDs
+        summaryAbsolutePath: AbsoluteFilePath | undefined;
+        contents: ParsedApiReferenceLayoutItem[];
+        slug: string | undefined;
+        hidden: boolean | undefined;
+        icon: string | undefined;
+        skipUrlSlug: boolean | undefined;
+    }
+    export interface Package {
+        type: "package";
+        title: string | undefined; // defaults to subpackage title
+        package: string; // subpackage ID
         summaryAbsolutePath: AbsoluteFilePath | undefined;
-        items: ParsedApiNavigationItem[];
+        contents: ParsedApiReferenceLayoutItem[];
+        slug: string | undefined;
+        hidden: boolean | undefined;
+        icon: string | undefined;
+        skipUrlSlug: boolean | undefined;
+    }
+
+    export interface Endpoint {
+        type: "endpoint";
+        endpoint: string; // endpoint locator
+        title: string | undefined;
+        icon: string | undefined;
+        slug: string | undefined;
+        hidden: boolean | undefined;
     }
 
     export interface Item {
@@ -223,7 +251,10 @@ export declare namespace ParsedApiNavigationItem {
     }
 }
 
-export type ParsedApiNavigationItem =
-    | ParsedApiNavigationItem.Item
-    | ParsedApiNavigationItem.Subpackage
-    | DocsNavigationItem.Page;
+export type ParsedApiReferenceLayoutItem =
+    | ParsedApiReferenceLayoutItem.Item
+    | ParsedApiReferenceLayoutItem.Section
+    | ParsedApiReferenceLayoutItem.Package
+    | ParsedApiReferenceLayoutItem.Endpoint
+    | DocsNavigationItem.Page
+    | DocsNavigationItem.Link;

packages/cli/configuration/src/docs-yml/getAllPages.ts

@@ -1,7 +1,11 @@
 import { assertNever } from "@fern-api/core-utils";
 import { AbsoluteFilePath, RelativeFilePath, relativize } from "@fern-api/fs-utils";
 import { readFile } from "fs/promises";
-import { DocsNavigationConfiguration, DocsNavigationItem, ParsedApiNavigationItem } from "./ParsedDocsConfiguration";
+import {
+    DocsNavigationConfiguration,
+    DocsNavigationItem,
+    ParsedApiReferenceLayoutItem
+} from "./ParsedDocsConfiguration";
 
 export async function getAllPages({
     navigation,
@@ -70,7 +74,7 @@ export async function getAllPagesFromNavigationItem({
             const toRet = combineMaps(
                 await Promise.all(
                     item.navigation.map((apiNavigation) =>
-                        getAllPagesFromApiNavigationItem({ item: apiNavigation, absolutePathToFernFolder })
+                        getAllPagesFromApiReferenceLayoutItem({ item: apiNavigation, absolutePathToFernFolder })
                     )
                 )
             );
@@ -106,11 +110,11 @@ function combineMaps(maps: Record<RelativeFilePath, string>[]) {
     return maps.reduce((acc, record) => ({ ...acc, ...record }), {});
 }
 
-async function getAllPagesFromApiNavigationItem({
+async function getAllPagesFromApiReferenceLayoutItem({
     item,
     absolutePathToFernFolder
 }: {
-    item: ParsedApiNavigationItem;
+    item: ParsedApiReferenceLayoutItem;
     absolutePathToFernFolder: AbsoluteFilePath;
 }): Promise<Record<RelativeFilePath, string>> {
     if (item.type === "page") {
@@ -119,11 +123,11 @@ async function getAllPagesFromApiNavigationItem({
                 await readFile(item.absolutePath)
             ).toString()
         };
-    } else if (item.type === "subpackage") {
+    } else if (item.type === "package" || item.type === "section") {
         const toRet = combineMaps(
             await Promise.all(
-                item.items.map(async (subItem) => {
-                    return await getAllPagesFromApiNavigationItem({ item: subItem, absolutePathToFernFolder });
+                item.contents.map(async (subItem) => {
+                    return await getAllPagesFromApiReferenceLayoutItem({ item: subItem, absolutePathToFernFolder });
                 })
             )
         );