From 32ae9ed4367b5ede9129e3366452da4f2a0c66ae Mon Sep 17 00:00:00 2001 From: Andrew Jiang Date: Wed, 10 Apr 2024 13:12:40 +1000 Subject: [PATCH] feat: hidden, skipurlslug, and icon (#3352) impl: hidden, skipurlslug, and icon --- .../configuration/fern/definition/docs.yml | 8 ++++++ .../src/docs-yml/ParsedDocsConfiguration.ts | 8 ++++++ .../src/docs-yml/parseDocsConfiguration.ts | 25 +++++++++++-------- .../docs/types/ApiSectionConfiguration.ts | 3 +++ .../resources/docs/types/PageConfiguration.ts | 2 ++ .../docs/types/SectionConfiguration.ts | 3 +++ .../docs/types/ApiSectionConfiguration.ts | 6 +++++ .../resources/docs/types/PageConfiguration.ts | 4 +++ .../docs/types/SectionConfiguration.ts | 6 +++++ .../src/publishDocs.ts | 9 +++++-- 10 files changed, 62 insertions(+), 12 deletions(-) diff --git a/packages/cli/configuration/fern/definition/docs.yml b/packages/cli/configuration/fern/definition/docs.yml index 679d4945027..d6a36a9acfd 100644 --- a/packages/cli/configuration/fern/definition/docs.yml +++ b/packages/cli/configuration/fern/definition/docs.yml @@ -350,6 +350,8 @@ types: page: string path: string slug: optional + icon: optional + hidden: optional SectionConfiguration: properties: @@ -357,6 +359,9 @@ types: contents: list collapsed: optional slug: optional + icon: optional + hidden: optional + skip-slug: optional ApiSectionConfiguration: properties: @@ -377,6 +382,9 @@ types: type: optional 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 + hidden: optional + skip-slug: optional ApiNavigationItem: docs: | diff --git a/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts index 60afcb9fe5e..86e6d422a6a 100644 --- a/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts @@ -137,27 +137,35 @@ export declare namespace DocsNavigationItem { export interface Page { type: "page"; title: string; + icon: string | undefined; absolutePath: AbsoluteFilePath; slug: string | undefined; + hidden: boolean | undefined; } export interface Section { type: "section"; title: string; + icon: string | undefined; contents: DocsNavigationItem[]; collapsed: boolean | undefined; slug: string | undefined; + hidden: boolean | undefined; + skipUrlSlug: boolean | undefined; } export interface ApiSection { type: "apiSection"; title: string; + icon: string | undefined; apiName: string | undefined; audiences: Audiences; showErrors: boolean; snippetsConfiguration: SnippetsConfiguration | undefined; summaryAbsolutePath: AbsoluteFilePath | undefined; navigation: ParsedApiNavigationItem[]; + hidden: boolean | undefined; + skipUrlSlug: boolean | undefined; } export interface Link { diff --git a/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts index cfb443ef414..5ab9787a234 100644 --- a/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts @@ -522,26 +522,32 @@ async function convertNavigationItem({ absolutePath: absolutePathToConfig, rawUnresolvedFilepath: rawConfig.path }), - slug: rawConfig.slug ?? undefined + slug: rawConfig.slug, + icon: rawConfig.icon, + hidden: rawConfig.hidden }; } if (isRawSectionConfig(rawConfig)) { return { type: "section", title: rawConfig.section, + icon: rawConfig.icon, contents: await Promise.all( rawConfig.contents.map((item) => convertNavigationItem({ rawConfig: item, absolutePathToFernFolder, absolutePathToConfig, context }) ) ), slug: rawConfig.slug ?? undefined, - collapsed: rawConfig.collapsed ?? undefined + collapsed: rawConfig.collapsed ?? undefined, + hidden: rawConfig.hidden ?? undefined, + skipUrlSlug: rawConfig.skipSlug ?? false }; } if (isRawApiSectionConfig(rawConfig)) { return { type: "apiSection", title: rawConfig.api, + icon: rawConfig.icon, apiName: rawConfig.apiName ?? undefined, audiences: rawConfig.audiences != null ? { type: "select", audiences: rawConfig.audiences } : { type: "all" }, @@ -557,7 +563,9 @@ async function convertNavigationItem({ absolutePath: absolutePathToConfig, rawUnresolvedFilepath: rawConfig.summary }) - : undefined + : undefined, + hidden: rawConfig.hidden ?? undefined, + skipUrlSlug: rawConfig.skipSlug ?? false }; } if (isRawLinkConfig(rawConfig)) { @@ -575,12 +583,7 @@ function parseApiNavigationItem( absolutePathToConfig: AbsoluteFilePath ): ParsedApiNavigationItem[] { if (typeof item === "string") { - return [ - { - type: "item", - value: item - } - ]; + return [{ type: "item", value: item }]; } // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -593,7 +596,9 @@ function parseApiNavigationItem( absolutePath: absolutePathToConfig, rawUnresolvedFilepath: item.path }), - slug: item.slug ?? undefined + slug: item.slug, + icon: item.icon, + hidden: item.hidden } ]; } diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiSectionConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiSectionConfiguration.ts index 36e61ff1887..ddcb06103d0 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiSectionConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiSectionConfiguration.ts @@ -16,4 +16,7 @@ export interface ApiSectionConfiguration { summary?: string; /** 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. */ layout?: FernDocsConfig.ApiNavigationItems; + icon?: string; + hidden?: boolean; + skipSlug?: boolean; } diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/PageConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/PageConfiguration.ts index 766e6c2a913..4aa656757c3 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/PageConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/PageConfiguration.ts @@ -6,4 +6,6 @@ export interface PageConfiguration { page: string; path: string; slug?: string; + icon?: string; + hidden?: boolean; } diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/SectionConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/SectionConfiguration.ts index f25073b328a..01349177447 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/SectionConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/SectionConfiguration.ts @@ -9,4 +9,7 @@ export interface SectionConfiguration { contents: FernDocsConfig.NavigationItem[]; collapsed?: boolean; slug?: string; + icon?: string; + hidden?: boolean; + skipSlug?: boolean; } diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiSectionConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiSectionConfiguration.ts index 30c5fb6c2bb..26e6a8ca8eb 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiSectionConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiSectionConfiguration.ts @@ -17,6 +17,9 @@ export const ApiSectionConfiguration: core.serialization.ObjectSchema< snippets: core.serialization.lazyObject(async () => (await import("../../..")).SnippetsConfiguration).optional(), summary: core.serialization.string().optional(), layout: core.serialization.lazy(async () => (await import("../../..")).ApiNavigationItems).optional(), + icon: core.serialization.string().optional(), + hidden: core.serialization.boolean().optional(), + skipSlug: core.serialization.property("skip-slug", core.serialization.boolean().optional()), }); export declare namespace ApiSectionConfiguration { @@ -28,5 +31,8 @@ export declare namespace ApiSectionConfiguration { snippets?: serializers.SnippetsConfiguration.Raw | null; summary?: string | null; layout?: serializers.ApiNavigationItems.Raw | null; + icon?: string | null; + hidden?: boolean | null; + "skip-slug"?: boolean | null; } } diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/PageConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/PageConfiguration.ts index b4af4a12fb5..ef9314b1b1e 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/PageConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/PageConfiguration.ts @@ -13,6 +13,8 @@ export const PageConfiguration: core.serialization.ObjectSchema< page: core.serialization.string(), path: core.serialization.string(), slug: core.serialization.string().optional(), + icon: core.serialization.string().optional(), + hidden: core.serialization.boolean().optional(), }); export declare namespace PageConfiguration { @@ -20,5 +22,7 @@ export declare namespace PageConfiguration { page: string; path: string; slug?: string | null; + icon?: string | null; + hidden?: boolean | null; } } diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/SectionConfiguration.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/SectionConfiguration.ts index c1a71d26ec9..925abdf1fc0 100644 --- a/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/SectionConfiguration.ts +++ b/packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/SectionConfiguration.ts @@ -14,6 +14,9 @@ export const SectionConfiguration: core.serialization.ObjectSchema< contents: core.serialization.list(core.serialization.lazy(async () => (await import("../../..")).NavigationItem)), collapsed: core.serialization.boolean().optional(), slug: core.serialization.string().optional(), + icon: core.serialization.string().optional(), + hidden: core.serialization.boolean().optional(), + skipSlug: core.serialization.property("skip-slug", core.serialization.boolean().optional()), }); export declare namespace SectionConfiguration { @@ -22,5 +25,8 @@ export declare namespace SectionConfiguration { contents: serializers.NavigationItem.Raw[]; collapsed?: boolean | null; slug?: string | null; + icon?: string | null; + hidden?: boolean | null; + "skip-slug"?: boolean | null; } } diff --git a/packages/cli/generation/remote-generation/remote-workspace-runner/src/publishDocs.ts b/packages/cli/generation/remote-generation/remote-workspace-runner/src/publishDocs.ts index aabfe9b4bc6..3127fbb0185 100644 --- a/packages/cli/generation/remote-generation/remote-workspace-runner/src/publishDocs.ts +++ b/packages/cli/generation/remote-generation/remote-workspace-runner/src/publishDocs.ts @@ -856,9 +856,11 @@ async function convertNavigationItem({ convertedItem = { type: "page", title: item.title, + icon: item.icon, id: relative(dirname(parsedDocsConfig.absoluteFilepath), item.absolutePath), urlSlugOverride: item.slug, - fullSlug: fullSlugs[item.absolutePath]?.fullSlug?.split("/") + fullSlug: fullSlugs[item.absolutePath]?.fullSlug?.split("/"), + hidden: item.hidden }; break; } @@ -882,7 +884,10 @@ async function convertNavigationItem({ title: item.title, items: sectionItems.map((sectionItem) => sectionItem.item), urlSlugOverride: item.slug, - collapsed: item.collapsed + collapsed: item.collapsed, + icon: item.icon, + hidden: item.hidden, + skipUrlSlug: item.skipUrlSlug }; for (const sectionItem of sectionItems) { pages = {