feat(cli): add library-docs navigation item support for documentation

docs-yml.schema.json

@@ -2278,6 +2278,128 @@
       ],
       "additionalProperties": false
     },
+    "docs.LibraryReferenceConfiguration": {
+      "type": "object",
+      "properties": {
+        "viewers": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.Role"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "orphaned": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "library-docs": {
+          "type": "string"
+        },
+        "branch": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "package-path": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "title": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "slug": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "icon": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "hidden": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "collapsed": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "availability": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.Availability"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "library-docs"
+      ],
+      "additionalProperties": false
+    },
     "docs.ChangelogConfiguration": {
       "type": "object",
       "properties": {
@@ -2483,6 +2605,9 @@
         {
           "$ref": "#/definitions/docs.ApiReferenceConfiguration"
         },
+        {
+          "$ref": "#/definitions/docs.LibraryReferenceConfiguration"
+        },
         {
           "$ref": "#/definitions/docs.LinkConfiguration"
         },

fern/apis/docs-yml/definition/docs.yml

@@ -525,6 +525,7 @@ types:
       - PageConfiguration
       - SectionConfiguration
       - ApiReferenceConfiguration
+      - LibraryReferenceConfiguration
       - LinkConfiguration
       - ChangelogConfiguration
       - FolderConfiguration
@@ -1095,6 +1096,40 @@ types:
         type: optional<PlaygroundSettings>
         docs: Settings for the api playground that affects all endpoints.
 
+  LibraryReferenceConfiguration:
+    extends: [WithPermissions, WithFeatureFlags]
+    docs: |
+      Configuration for generating and displaying library documentation from source code.
+      The library docs are generated from a GitHub repository and merged into the navigation.
+    properties:
+      library-docs:
+        type: string
+        docs: |
+          GitHub URL to the repository containing the library source code.
+          Example: https://github.com/NVIDIA/NeMo-RL
+      branch:
+        type: optional<string>
+        docs: Git branch to clone. Defaults to the repository's default branch.
+      package-path:
+        type: optional<string>
+        docs: |
+          Path to the package within the repository. Useful for monorepos where
+          the library is not at the root level.
+      title:
+        type: optional<string>
+        docs: |
+          Navigation title for the library reference section.
+          @default: "Library Reference"
+      slug:
+        type: optional<string>
+        docs: |
+          URL slug for the library reference pages.
+          @default: "library-reference"
+      icon: optional<string>
+      hidden: optional<boolean>
+      collapsed: optional<boolean>
+      availability: optional<Availability>
+
   ApiReferenceLayoutItem:
     docs: |
       Use the `layout` object to customize the order that your API endpoints

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

@@ -129,6 +129,9 @@ export function getAllPagesFromNavigationItem({ item }: { item: docsYml.DocsNavi
             ]);
         case "changelog":
             return item.changelog;
+        case "librarySection":
+            // Library docs pages are generated by FDR, not from local files
+            return [];
         default:
             assertNever(item);
     }

packages/cli/configuration-loader/src/docs-yml/getReferencedApiSections.ts

@@ -100,6 +100,7 @@ export function visitDocsNavigationItem({
         case "page":
         case "link":
         case "changelog":
+        case "librarySection":
             return;
         default:
             assertNever(item);

packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts

@@ -1086,6 +1086,23 @@ async function convertNavigationItem({
             context
         });
     }
+    if (isRawLibrarySectionConfig(rawConfig)) {
+        return {
+            type: "librarySection",
+            githubUrl: rawConfig.libraryDocs,
+            branch: rawConfig.branch ?? undefined,
+            packagePath: rawConfig.packagePath ?? undefined,
+            title: rawConfig.title ?? undefined,
+            slug: rawConfig.slug ?? undefined,
+            icon: resolveIconPath(rawConfig.icon, absolutePathToConfig),
+            hidden: rawConfig.hidden ?? undefined,
+            collapsed: rawConfig.collapsed ?? undefined,
+            availability: rawConfig.availability ?? undefined,
+            viewers: parseRoles(rawConfig.viewers),
+            orphaned: rawConfig.orphaned,
+            featureFlags: convertFeatureFlag(rawConfig.featureFlag)
+        };
+    }
     assertNever(rawConfig);
 }
 
@@ -1262,6 +1279,10 @@ function isRawFolderConfig(item: unknown): item is docsYml.RawSchemas.FolderConf
     return isPlainObject(item) && typeof item.folder === "string";
 }
 
+function isRawLibrarySectionConfig(item: unknown): item is docsYml.RawSchemas.LibraryReferenceConfiguration {
+    return isPlainObject(item) && typeof item.libraryDocs === "string";
+}
+
 function isRawApiRefSectionConfiguration(item: unknown): item is docsYml.RawSchemas.ApiReferenceSectionConfiguration {
     return isPlainObject(item) && typeof item.section === "string" && Array.isArray(item.contents);
 }

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

@@ -293,6 +293,7 @@ export type DocsNavigationItem =
     | DocsNavigationItem.Page
     | DocsNavigationItem.Section
     | DocsNavigationItem.ApiSection
+    | DocsNavigationItem.LibrarySection
     | DocsNavigationItem.Link
     | DocsNavigationItem.Changelog;
 
@@ -370,6 +371,26 @@ export declare namespace DocsNavigationItem {
         slug: string | undefined;
     }
 
+    export interface LibrarySection
+        extends CjsFdrSdk.navigation.v1.WithPermissions,
+            CjsFdrSdk.navigation.latest.WithFeatureFlags {
+        type: "librarySection";
+        /** GitHub URL to the repository containing the library source code */
+        githubUrl: string;
+        /** Git branch to clone. Defaults to default branch. */
+        branch: string | undefined;
+        /** Path to package within repo. For monorepos. */
+        packagePath: string | undefined;
+        /** Navigation title. Defaults to "Library Reference". */
+        title: string | undefined;
+        /** URL slug. Defaults to "library-reference". */
+        slug: string | undefined;
+        icon: string | AbsoluteFilePath | undefined;
+        hidden: boolean | undefined;
+        collapsed: boolean | undefined;
+        availability: Availability | undefined;
+    }
+
     export interface VersionedSnippetLanguageConfiguration {
         package: string;
         version: string;

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/LibraryReferenceConfiguration.ts

@@ -0,0 +1,38 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernDocsConfig from "../../../index";
+
+/**
+ * Configuration for generating and displaying library documentation from source code.
+ * The library docs are generated from a GitHub repository and merged into the navigation.
+ */
+export interface LibraryReferenceConfiguration extends FernDocsConfig.WithPermissions, FernDocsConfig.WithFeatureFlags {
+    /**
+     * GitHub URL to the repository containing the library source code.
+     * Example: https://github.com/NVIDIA/NeMo-RL
+     */
+    libraryDocs: string;
+    /** Git branch to clone. Defaults to the repository's default branch. */
+    branch?: string;
+    /**
+     * Path to the package within the repository. Useful for monorepos where
+     * the library is not at the root level.
+     */
+    packagePath?: string;
+    /**
+     * Navigation title for the library reference section.
+     * @default: "Library Reference"
+     */
+    title?: string;
+    /**
+     * URL slug for the library reference pages.
+     * @default: "library-reference"
+     */
+    slug?: string;
+    icon?: string;
+    hidden?: boolean;
+    collapsed?: boolean;
+    availability?: FernDocsConfig.Availability;
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/NavigationItem.ts

@@ -8,6 +8,7 @@ export type NavigationItem =
     | FernDocsConfig.PageConfiguration
     | FernDocsConfig.SectionConfiguration
     | FernDocsConfig.ApiReferenceConfiguration
+    | FernDocsConfig.LibraryReferenceConfiguration
     | FernDocsConfig.LinkConfiguration
     | FernDocsConfig.ChangelogConfiguration
     | FernDocsConfig.FolderConfiguration;

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts

@@ -75,6 +75,7 @@ export * from "./ChangelogConfiguration";
 export * from "./SectionConfiguration";
 export * from "./FolderConfiguration";
 export * from "./ApiReferenceConfiguration";
+export * from "./LibraryReferenceConfiguration";
 export * from "./ApiReferenceLayoutItem";
 export * from "./ApiReferenceSectionConfiguration";
 export * from "./ApiReferencePackageConfiguration";

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/LibraryReferenceConfiguration.ts

@@ -0,0 +1,42 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../../index";
+import * as FernDocsConfig from "../../../../api/index";
+import * as core from "../../../../core";
+import { Availability } from "./Availability";
+import { WithPermissions } from "./WithPermissions";
+import { WithFeatureFlags } from "./WithFeatureFlags";
+
+export const LibraryReferenceConfiguration: core.serialization.ObjectSchema<
+    serializers.LibraryReferenceConfiguration.Raw,
+    FernDocsConfig.LibraryReferenceConfiguration
+> = core.serialization
+    .object({
+        libraryDocs: core.serialization.property("library-docs", core.serialization.string()),
+        branch: core.serialization.string().optional(),
+        packagePath: core.serialization.property("package-path", core.serialization.string().optional()),
+        title: core.serialization.string().optional(),
+        slug: core.serialization.string().optional(),
+        icon: core.serialization.string().optional(),
+        hidden: core.serialization.boolean().optional(),
+        collapsed: core.serialization.boolean().optional(),
+        availability: Availability.optional(),
+    })
+    .extend(WithPermissions)
+    .extend(WithFeatureFlags);
+
+export declare namespace LibraryReferenceConfiguration {
+    export interface Raw extends WithPermissions.Raw, WithFeatureFlags.Raw {
+        "library-docs": string;
+        branch?: string | null;
+        "package-path"?: string | null;
+        title?: string | null;
+        slug?: string | null;
+        icon?: string | null;
+        hidden?: boolean | null;
+        collapsed?: boolean | null;
+        availability?: Availability.Raw | null;
+    }
+}

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/NavigationItem.ts

@@ -7,6 +7,7 @@ import * as FernDocsConfig from "../../../../api/index";
 import * as core from "../../../../core";
 import { PageConfiguration } from "./PageConfiguration";
 import { ApiReferenceConfiguration } from "./ApiReferenceConfiguration";
+import { LibraryReferenceConfiguration } from "./LibraryReferenceConfiguration";
 import { LinkConfiguration } from "./LinkConfiguration";
 import { ChangelogConfiguration } from "./ChangelogConfiguration";
 import { FolderConfiguration } from "./FolderConfiguration";
@@ -16,6 +17,7 @@ export const NavigationItem: core.serialization.Schema<serializers.NavigationIte
         PageConfiguration,
         core.serialization.lazyObject(() => serializers.SectionConfiguration),
         ApiReferenceConfiguration,
+        LibraryReferenceConfiguration,
         LinkConfiguration,
         ChangelogConfiguration,
         FolderConfiguration,
@@ -26,6 +28,7 @@ export declare namespace NavigationItem {
         | PageConfiguration.Raw
         | serializers.SectionConfiguration.Raw
         | ApiReferenceConfiguration.Raw
+        | LibraryReferenceConfiguration.Raw
         | LinkConfiguration.Raw
         | ChangelogConfiguration.Raw
         | FolderConfiguration.Raw;