allow merging subpackages

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

@@ -444,18 +444,24 @@ types:
       - LinkConfiguration
       - ApiPackageConfiguration
 
+  SubpackageOrSubpackages:
+    discriminated: false
+    union:
+      - string
+      - list<string>
+
   ApiPackageConfiguration:
     properties:
       package:
         type: string
         docs: |
           The title of the api package that will be displayed in the sidebar.
 
-          Alternatively, if this is a Subpackage ID. The title of this section will be inherited from the subpackage.
+          Alternatively, `subpackage` is unset, and this is a Subpackage ID. The title of this section will be inherited from the subpackage.
           Any endpoints that are not explicitly defined within the contents of this object will be implicitly included.
-      title:
-        type: optional<string>
-        docs: This overrides the title of the package.
+      subpackage:
+        type: optional<SubpackageOrSubpackages>
+        docs: If `subpackage` is set, this section will inherit the endpoints from the specified subpackage(s).
       summary:
         type: optional<string>
         docs: |

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

@@ -216,7 +216,7 @@ export declare namespace ParsedApiNavigationItem {
     export interface Package {
         type: "package";
         package: string; // title or subpackage ID
-        titleOverride: string | undefined;
+        subpackages: string[]; // subpackage IDs
         summaryAbsolutePath: AbsoluteFilePath | undefined;
         contents: ParsedApiNavigationItem[];
         slug: string | undefined;

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

@@ -592,7 +592,7 @@ function parseApiNavigationItem(
             {
                 type: "package",
                 package: item.package,
-                titleOverride: item.title,
+                subpackages: typeof item.subpackage === "string" ? [item.subpackage] : item.subpackage ?? [],
                 summaryAbsolutePath: resolveFilepath(item.summary, absolutePathToConfig),
                 contents: item.contents.flatMap((value) => parseApiNavigationItem(value, absolutePathToConfig)),
                 slug: item.slug,
@@ -607,7 +607,7 @@ function parseApiNavigationItem(
         ([key, values]): ParsedApiNavigationItem.Package => ({
             type: "package",
             package: key,
-            titleOverride: undefined,
+            subpackages: [],
             summaryAbsolutePath: undefined,
             contents: values.flatMap((value) => parseApiNavigationItem(value, absolutePathToConfig)),
             hidden: false,

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

@@ -8,12 +8,12 @@ export interface ApiPackageConfiguration {
     /**
      * The title of the api package that will be displayed in the sidebar.
      *
-     * Alternatively, if this is a Subpackage ID. The title of this section will be inherited from the subpackage.
+     * Alternatively, `subpackage` is unset, and this is a Subpackage ID. The title of this section will be inherited from the subpackage.
      * Any endpoints that are not explicitly defined within the contents of this object will be implicitly included.
      */
     package: string;
-    /** This overrides the title of the package. */
-    title?: string;
+    /** If `subpackage` is set, this section will inherit the endpoints from the specified subpackage(s). */
+    subpackage?: FernDocsConfig.SubpackageOrSubpackages;
     /** Relative path to the markdown file. This summary is displayed at the top of the API section. */
     summary?: string;
     contents: FernDocsConfig.ApiNavigationItems;

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

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+export type SubpackageOrSubpackages = string | string[];

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

@@ -31,6 +31,7 @@ export * from "./PageConfiguration";
 export * from "./SectionConfiguration";
 export * from "./ApiSectionConfiguration";
 export * from "./ApiNavigationItem";
+export * from "./SubpackageOrSubpackages";
 export * from "./ApiPackageConfiguration";
 export * from "./ApiNavigationItems";
 export * from "./LinkConfiguration";

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

@@ -11,7 +11,7 @@ export const ApiPackageConfiguration: core.serialization.ObjectSchema<
     FernDocsConfig.ApiPackageConfiguration
 > = core.serialization.object({
     package: core.serialization.string(),
-    title: core.serialization.string().optional(),
+    subpackage: core.serialization.lazy(async () => (await import("../../..")).SubpackageOrSubpackages).optional(),
     summary: core.serialization.string().optional(),
     contents: core.serialization.lazy(async () => (await import("../../..")).ApiNavigationItems),
     slug: core.serialization.string().optional(),
@@ -23,7 +23,7 @@ export const ApiPackageConfiguration: core.serialization.ObjectSchema<
 export declare namespace ApiPackageConfiguration {
     interface Raw {
         package: string;
-        title?: string | null;
+        subpackage?: serializers.SubpackageOrSubpackages.Raw | null;
         summary?: string | null;
         contents: serializers.ApiNavigationItems.Raw;
         slug?: string | null;

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

@@ -0,0 +1,19 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as serializers from "../../..";
+import * as FernDocsConfig from "../../../../api";
+import * as core from "../../../../core";
+
+export const SubpackageOrSubpackages: core.serialization.Schema<
+    serializers.SubpackageOrSubpackages.Raw,
+    FernDocsConfig.SubpackageOrSubpackages
+> = core.serialization.undiscriminatedUnion([
+    core.serialization.string(),
+    core.serialization.list(core.serialization.string()),
+]);
+
+export declare namespace SubpackageOrSubpackages {
+    type Raw = string | string[];
+}

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

@@ -31,6 +31,7 @@ export * from "./PageConfiguration";
 export * from "./SectionConfiguration";
 export * from "./ApiSectionConfiguration";
 export * from "./ApiNavigationItem";
+export * from "./SubpackageOrSubpackages";
 export * from "./ApiPackageConfiguration";
 export * from "./ApiNavigationItems";
 export * from "./LinkConfiguration";

packages/cli/docs-resolver/src/ApiReferenceNodeConverter.ts

@@ -143,8 +143,6 @@ export class ApiReferenceNodeConverter {
         parentSlug: FernNavigation.SlugGenerator,
         idgen: NodeIdGenerator
     ): FernNavigation.ApiPackageNode {
-        const subpackage = this.#holder.getSubpackage(pkg.package);
-
         const overviewPageId =
             pkg.summaryAbsolutePath != null
                 ? FernNavigation.PageId(this.toRelativeFilepath(pkg.summaryAbsolutePath))
@@ -153,13 +151,72 @@ export class ApiReferenceNodeConverter {
         const maybeFullSlug =
             pkg.summaryAbsolutePath != null ? this.markdownFilesToFullSlugs.get(pkg.summaryAbsolutePath) : undefined;
 
+        if (pkg.subpackages.length > 0) {
+            let subpackage: APIV1Read.ApiDefinitionPackage | undefined = undefined;
+            let i = 0;
+            while (subpackage == null && i < pkg.subpackages.length) {
+                subpackage = this.#holder.getSubpackage(pkg.subpackages[i]!);
+                i++;
+            }
+
+            if (subpackage != null) {
+                const subpackageId = ApiDefinitionHolder.getSubpackageId(subpackage);
+                const subpackageNodeId = idgen.append(subpackageId);
+                this.#visitedSubpackages.add(subpackageId);
+                this.#nodeIdToSubpackageId.set(subpackageNodeId.get(), subpackageId);
+                const urlSlug =
+                    pkg.slug ??
+                    (isSubpackage(subpackage)
+                        ? subpackage.urlSlug
+                        : this.apiSection.slug ?? kebabCase(this.apiSection.title));
+                const slug = parentSlug.apply({
+                    fullSlug: maybeFullSlug?.split("/"),
+                    skipUrlSlug: pkg.skipUrlSlug,
+                    urlSlug
+                });
+                const convertedItems: FernNavigation.ApiPackageChild[] = [];
+                pkg.subpackages.forEach((subpackageId) => {
+                    const subpackage = this.#holder.getSubpackage(subpackageId);
+                    if (subpackage == null) {
+                        this.taskContext.logger.error(
+                            `Subpackage ${subpackageId} not found in ${this.apiDefinitionId}`
+                        );
+                        return;
+                    }
+                    this.#visitedSubpackages.add(subpackageId);
+                    this.#nodeIdToSubpackageId.set(subpackageNodeId.get(), subpackageId);
+                    convertedItems.push(
+                        ...this.#convertApiNavigationItems(pkg.contents, subpackage, slug, subpackageNodeId)
+                    );
+                });
+                return {
+                    id: subpackageNodeId.get(),
+                    type: "apiPackage",
+                    children: convertedItems,
+                    title: pkg.package,
+                    slug: slug.get(),
+                    icon: pkg.icon,
+                    hidden: pkg.hidden,
+                    overviewPageId,
+                    availability: undefined,
+                    apiDefinitionId: this.apiDefinitionId,
+                    pointsTo: undefined
+                };
+            }
+        }
+
+        const subpackage = this.#holder.getSubpackage(pkg.package);
+
         if (subpackage != null) {
             const subpackageId = ApiDefinitionHolder.getSubpackageId(subpackage);
             const subpackageNodeId = idgen.append(subpackageId);
             this.#visitedSubpackages.add(subpackageId);
             this.#nodeIdToSubpackageId.set(subpackageNodeId.get(), subpackageId);
             const urlSlug =
-                pkg.slug ?? (isSubpackage(subpackage) ? subpackage.urlSlug : kebabCase(pkg.titleOverride ?? ""));
+                pkg.slug ??
+                (isSubpackage(subpackage)
+                    ? subpackage.urlSlug
+                    : this.apiSection.slug ?? kebabCase(this.apiSection.title));
             const slug = parentSlug.apply({
                 fullSlug: maybeFullSlug?.split("/"),
                 skipUrlSlug: pkg.skipUrlSlug,
@@ -170,11 +227,9 @@ export class ApiReferenceNodeConverter {
                 id: subpackageNodeId.get(),
                 type: "apiPackage",
                 children: convertedItems,
-                title:
-                    pkg.titleOverride ??
-                    (isSubpackage(subpackage)
-                        ? subpackage.displayName ?? titleCase(subpackage.name)
-                        : this.apiSection.title),
+                title: isSubpackage(subpackage)
+                    ? subpackage.displayName ?? titleCase(subpackage.name)
+                    : this.apiSection.title,
                 slug: slug.get(),
                 icon: pkg.icon,
                 hidden: pkg.hidden,
@@ -184,7 +239,7 @@ export class ApiReferenceNodeConverter {
                 pointsTo: undefined
             };
         } else {
-            const urlSlug = pkg.slug ?? kebabCase(pkg.titleOverride ?? pkg.package);
+            const urlSlug = pkg.slug ?? kebabCase(pkg.package);
             const slug = parentSlug.apply({
                 fullSlug: maybeFullSlug?.split("/"),
                 skipUrlSlug: pkg.skipUrlSlug,
@@ -195,7 +250,7 @@ export class ApiReferenceNodeConverter {
                 id: idgen.append(kebabCase(pkg.package)).get(),
                 type: "apiPackage",
                 children: convertedItems,
-                title: pkg.titleOverride ?? pkg.package,
+                title: pkg.package,
                 slug: slug.get(),
                 icon: pkg.icon,
                 hidden: pkg.hidden,
@@ -291,8 +346,7 @@ export class ApiReferenceNodeConverter {
             }
             const subpackage = this.#holder.getSubpackage(subpackageId);
             if (subpackage == null) {
-                // eslint-disable-next-line no-console
-                console.error(`Subpackage ${subpackageId} not found in ${this.apiDefinitionId}`);
+                this.taskContext.logger.error(`Subpackage ${subpackageId} not found in ${this.apiDefinitionId}`);
                 return;
             }