custom segment write key (#4238)

* update cli to use default language * update fern cli * checkpoint * add analytics config * add docs page to talk about analytics block * fix docs errors
fern-api · Aug 8, 2024 · f925fe4 · f925fe4
1 parent f641a5a
commit f925fe4
Show file tree

Hide file tree

Showing 25 changed files with 156 additions and 37 deletions.
diff --git a/.pnp.cjs b/.pnp.cjs
diff --git a/...98.18-aaf13f7f5-28d1ceb312-2cab59acf6.zip → ...98.18-ff8e48d2c-079b2989be-769cb23e52.zip b/...98.18-aaf13f7f5-28d1ceb312-2cab59acf6.zip → ...98.18-ff8e48d2c-079b2989be-769cb23e52.zip
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -305,6 +305,10 @@ navigation:
           - page: ReadMe
             slug: readme
             path: ./pages/docs/comparison/readme.mdx
+      - section: Analytics
+        contents:
+          - page: Segment
+            path: ./pages/docs/analytics/segment.mdx
   - tab: cli-api
     layout:
       - section: CLI Reference

diff --git a/fern/pages/docs/analytics/segment.mdx b/fern/pages/docs/analytics/segment.mdx
@@ -0,0 +1,33 @@
+---
+title: Segment
+description: Learn how to integrate Fern Docs with Segment to track user behavior and analytics.
+---
+
+<Note>
+Currently we only support Segment via a custom writeKey in the docs.yml file, however you can add other providers to your docs page through [Custom Javascript](/learn/docs/building-your-docs/custom-css-js). 
+We are also working on adding support for additional analytics tools via the docs.yml file analytics block!
+</Note>
+
+## Add Segment to your Docs
+
+To add Segment to your Docs, you need to add the Segment writeKey to your `docs.yml` file.
+
+### Get your Segment writeKey
+
+1. Log in to your Segment account.
+2. Go to the workspace where you want to add the Docs integration.
+3. Click on the Source you want to track.'
+4. Click on the `Settings` tab.
+5. Copy the `Write Key` from the `API Keys` section.
+
+### Add the Segment writeKey to your Docs
+
+In your `docs.yml` file, add the Segment writeKey:
+
+<CodeBlock title="docs.yml">
+```yaml
+analytics:
+  segment:
+    write-key: YOUR_SEGMENT_WRITE_KEY
+```
+</CodeBlock>
diff --git a/packages/cli/configuration/fern/definition/docs.yml b/packages/cli/configuration/fern/definition/docs.yml
@@ -20,13 +20,26 @@ types:
       - jvm
       - ts
       - js
+
+  AnalyticsConfig:
+    properties:
+      segment: optional<SegmentConfig>
+
+  SegmentConfig:
+    properties:
+      write-key: string
 
   DocsConfiguration:
     properties:
       instances: list<DocsInstance>
       title:
         type: optional<string>
         docs: used as tab bar title, and in the navbar if no logo is defined
+      analytics: 
+        type: optional<AnalyticsConfig>
+        docs: |
+          The `analytics` object allows you to configure analytics for your docs site.
+          Currently, only Segment is supported.
 
       # navigation
       tabs: optional<map<TabId, TabConfig>>

diff --git a/packages/cli/configuration/package.json b/packages/cli/configuration/package.json
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-fern/fiddle-sdk": "0.0.584",

diff --git a/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts
@@ -29,6 +29,7 @@ export interface ParsedDocsConfiguration {
     typography: TypographyConfig | undefined;
     layout: WithoutQuestionMarks<DocsV1Write.DocsLayoutConfig> | undefined;
     defaultLanguage: DocsV1Write.ProgrammingLanguage | undefined;
+    analyticsConfig: DocsV1Write.AnalyticsConfig | undefined;
 
     /* integrations */
     integrations: DocsV1Write.IntegrationsConfig | undefined;

diff --git a/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts b/packages/cli/configuration/src/docs-yml/parseDocsConfiguration.ts
@@ -59,7 +59,7 @@ export async function parseDocsConfiguration({
         colors,
         typography: rawTypography,
         layout,
-
+        analytics: analyticsConfig,
         /* integrations */
         integrations,
 
@@ -142,6 +142,7 @@ export async function parseDocsConfiguration({
         colors: convertColorsConfiguration(colors, context),
         typography,
         layout: convertLayoutConfig(layout),
+        analyticsConfig: rawDocsConfiguration.analytics,
 
         /* integrations */
         integrations,

diff --git a/...es/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnalyticsConfig.ts b/...es/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/AnalyticsConfig.ts
@@ -0,0 +1,9 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+import * as FernDocsConfig from "../../..";
+
+export interface AnalyticsConfig {
+    segment?: FernDocsConfig.SegmentConfig;
+}
diff --git a/.../cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/DocsConfiguration.ts b/.../cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/DocsConfiguration.ts
@@ -8,6 +8,11 @@ export interface DocsConfiguration {
     instances: FernDocsConfig.DocsInstance[];
     /** used as tab bar title, and in the navbar if no logo is defined */
     title?: string;
+    /**
+     * The `analytics` object allows you to configure analytics for your docs site.
+     * Currently, only Segment is supported.
+     */
+    analytics?: FernDocsConfig.AnalyticsConfig;
     tabs?: Record<FernDocsConfig.TabId, FernDocsConfig.TabConfig>;
     versions?: FernDocsConfig.VersionConfig[];
     landingPage?: FernDocsConfig.PageConfiguration;

diff --git a/...ages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/SegmentConfig.ts b/...ages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/SegmentConfig.ts
@@ -0,0 +1,7 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+export interface SegmentConfig {
+    writeKey: string;
+}
diff --git a/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts b/packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/index.ts
@@ -1,4 +1,6 @@
 export * from "./ProgrammingLanguage";
+export * from "./AnalyticsConfig";
+export * from "./SegmentConfig";
 export * from "./DocsConfiguration";
 export * from "./TabId";
 export * from "./TabConfig";

diff --git a/...figuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnalyticsConfig.ts b/...figuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/AnalyticsConfig.ts
@@ -0,0 +1,20 @@
+/**
+ * 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 AnalyticsConfig: core.serialization.ObjectSchema<
+    serializers.AnalyticsConfig.Raw,
+    FernDocsConfig.AnalyticsConfig
+> = core.serialization.object({
+    segment: core.serialization.lazyObject(async () => (await import("../../..")).SegmentConfig).optional(),
+});
+
+export declare namespace AnalyticsConfig {
+    interface Raw {
+        segment?: serializers.SegmentConfig.Raw | null;
+    }
+}
diff --git a/...guration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/DocsConfiguration.ts b/...guration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/DocsConfiguration.ts
@@ -14,6 +14,7 @@ export const DocsConfiguration: core.serialization.ObjectSchema<
         core.serialization.lazyObject(async () => (await import("../../..")).DocsInstance)
     ),
     title: core.serialization.string().optional(),
+    analytics: core.serialization.lazyObject(async () => (await import("../../..")).AnalyticsConfig).optional(),
     tabs: core.serialization
         .record(
             core.serialization.lazy(async () => (await import("../../..")).TabId),
@@ -63,6 +64,7 @@ export declare namespace DocsConfiguration {
     interface Raw {
         instances: serializers.DocsInstance.Raw[];
         title?: string | null;
+        analytics?: serializers.AnalyticsConfig.Raw | null;
         tabs?: Record<serializers.TabId.Raw, serializers.TabConfig.Raw> | null;
         versions?: serializers.VersionConfig.Raw[] | null;
         "landing-page"?: serializers.PageConfiguration.Raw | null;

diff --git a/...onfiguration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/SegmentConfig.ts b/...onfiguration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/SegmentConfig.ts
@@ -0,0 +1,20 @@
+/**
+ * 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 SegmentConfig: core.serialization.ObjectSchema<
+    serializers.SegmentConfig.Raw,
+    FernDocsConfig.SegmentConfig
+> = core.serialization.object({
+    writeKey: core.serialization.property("write-key", core.serialization.string()),
+});
+
+export declare namespace SegmentConfig {
+    interface Raw {
+        "write-key": string;
+    }
+}
diff --git a/...es/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts b/...es/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/index.ts
@@ -1,4 +1,6 @@
 export * from "./ProgrammingLanguage";
+export * from "./AnalyticsConfig";
+export * from "./SegmentConfig";
 export * from "./DocsConfiguration";
 export * from "./TabId";
 export * from "./TabConfig";

diff --git a/packages/cli/docs-markdown-utils/package.json b/packages/cli/docs-markdown-utils/package.json
@@ -27,7 +27,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "gray-matter": "^4.0.3",

diff --git a/packages/cli/docs-preview/package.json b/packages/cli/docs-preview/package.json
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@fern-api/docs-resolver": "workspace:*",
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",
     "@fern-api/logger": "workspace:*",

diff --git a/packages/cli/docs-resolver/package.json b/packages/cli/docs-resolver/package.json
@@ -30,7 +30,7 @@
     "@fern-api/configuration": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-markdown-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",

diff --git a/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts b/packages/cli/docs-resolver/src/DocsDefinitionResolver.ts
@@ -256,7 +256,7 @@ export class DocsDefinitionResolver {
             integrations: this.parsedDocsConfig.integrations,
             footerLinks: this.parsedDocsConfig.footerLinks,
             defaultLanguage: this.parsedDocsConfig.defaultLanguage,
-
+            analyticsConfig: this.parsedDocsConfig.analyticsConfig,
             // deprecated
             logo: undefined,
             logoV2: undefined,

diff --git a/packages/cli/ete-tests/package.json b/packages/cli/ete-tests/package.json
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@fern-api/configuration": "workspace:*",
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/logging-execa": "workspace:*",
     "@fern-typescript/fetcher": "workspace:*",

diff --git a/packages/cli/generation/remote-generation/remote-workspace-runner/package.json b/packages/cli/generation/remote-generation/remote-workspace-runner/package.json
@@ -32,7 +32,7 @@
     "@fern-api/core": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-resolver": "workspace:*",
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/ir-migrations": "workspace:*",

diff --git a/packages/cli/register/package.json b/packages/cli/register/package.json
@@ -31,7 +31,7 @@
     "@fern-api/configuration": "workspace:*",
     "@fern-api/core": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",
     "@fern-api/task-context": "workspace:*",

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -27,7 +27,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-api/fdr-sdk": "0.98.18-aaf13f7f5",
+    "@fern-api/fdr-sdk": "0.98.18-ff8e48d2c",
     "@fern-api/venus-api-sdk": "0.0.38",
     "@fern-fern/fdr-test-sdk": "^0.0.5297",
     "@fern-fern/fiddle-sdk": "0.0.584"