@fern-api/fern-api-dev 3.40.1 → 3.42.0

package/cli.cjs

@@ -1307518,6 +1307518,7 @@ __export(serialization_exports, {
   AiChatLocation: () => AiChatLocation2,
   AiChatModel: () => AiChatModel2,
   AiChatWebsiteDatasource: () => AiChatWebsiteDatasource,
+  AiExamplesConfig: () => AiExamplesConfig,
   AnalyticsConfig: () => AnalyticsConfig,
   AnnouncementConfig: () => AnnouncementConfig,
   ApiReferenceConfiguration: () => ApiReferenceConfiguration,
@@ -1307645,6 +1307646,7 @@ __export(docs_exports2, {
   AiChatLocation: () => AiChatLocation2,
   AiChatModel: () => AiChatModel2,
   AiChatWebsiteDatasource: () => AiChatWebsiteDatasource,
+  AiExamplesConfig: () => AiExamplesConfig,
   AnalyticsConfig: () => AnalyticsConfig,
   AnnouncementConfig: () => AnnouncementConfig,
   ApiReferenceConfiguration: () => ApiReferenceConfiguration,
@@ -1309152,6 +1309154,12 @@ var AnalyticsConfig = schemas_exports.object({
   ga4: GoogleAnalytics4Config.optional()
 });
 
+// ../configuration/lib/docs-yml/schemas/sdk/serialization/resources/docs/types/AiExamplesConfig.js
+var AiExamplesConfig = schemas_exports.object({
+  enabled: schemas_exports.boolean().optional(),
+  style: schemas_exports.string().optional()
+});
+
 // ../configuration/lib/docs-yml/schemas/sdk/serialization/resources/docs/types/CustomDomain.js
 var CustomDomain = schemas_exports.undiscriminatedUnion([
   schemas_exports.string(),
@@ -1309719,6 +1309727,7 @@ var DocsConfiguration = schemas_exports.object({
   languages: schemas_exports.list(Language2).optional(),
   aiChat: schemas_exports.property("ai-chat", AiChatConfig.optional()),
   aiSearch: schemas_exports.property("ai-search", AiChatConfig.optional()),
+  aiExamples: schemas_exports.property("ai-examples", AiExamplesConfig.optional()),
   metadata: MetadataConfig.optional(),
   redirects: schemas_exports.list(RedirectConfig).optional(),
   logo: LogoConfiguration.optional(),
@@ -1309770,11 +1309779,11 @@ var PlaygroundButtonSettings = schemas_exports.object({
 
 // ../configuration/lib/docs-yml/schemas/sdk/serialization/resources/docs/types/PlaygroundSettings.js
 var PlaygroundSettings = schemas_exports.object({
+  hidden: schemas_exports.boolean().optional(),
   environments: schemas_exports.list(schemas_exports.string()).optional(),
   button: PlaygroundButtonSettings.optional(),
   oauth: schemas_exports.boolean().optional(),
-  limitWebsocketMessagesPerConnection: schemas_exports.property("limit-websocket-messages-per-connection", schemas_exports.number().optional()),
-  hidden: schemas_exports.boolean().optional()
+  limitWebsocketMessagesPerConnection: schemas_exports.property("limit-websocket-messages-per-connection", schemas_exports.number().optional())
 });
 
 // ../configuration/lib/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiReferenceConfiguration.js
@@ -1415650,7 +1415659,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "3.40.1",
+          version: "3.42.0",
           usingAccessToken: true
         }
       });
@@ -1415749,7 +1415758,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "3.40.1",
+        version: "3.42.0",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -1495940,7 +1495949,7 @@ var CliContext = class {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "3.40.1";
+    return "3.42.0";
   }
   getCliName() {
     if (false) {
@@ -1507225,6 +1507234,7 @@ var OneOfSchema2 = schemas_exports8.union("type", {
 // ../api-importers/openapi/openapi-ir/lib/sdk/serialization/resources/finalIr/types/DiscriminatedOneOfSchema.js
 var DiscriminatedOneOfSchema = schemas_exports8.objectWithoutOptionalProperties({
   discriminantProperty: schemas_exports8.string(),
+  discriminantPropertyNameOverride: schemas_exports8.string().optional(),
   commonProperties: schemas_exports8.list(schemas_exports8.lazyObject(() => CommonProperty)),
   schemas: schemas_exports8.record(schemas_exports8.string(), schemas_exports8.lazy(() => Schema4))
 }).extend(WithSdkGroupName).extend(WithNamespace).extend(WithName3).extend(WithDescription).extend(WithAvailability3).extend(WithEncoding).extend(WithSource).extend(WithTitle).extend(WithInline);
@@ -1507714,6 +1507724,7 @@ var OneOfSchemaWithExample2 = schemas_exports8.union("type", {
 // ../api-importers/openapi/openapi-ir/lib/sdk/serialization/resources/parseIr/types/DiscriminatedOneOfSchemaWithExample.js
 var DiscriminatedOneOfSchemaWithExample = schemas_exports8.objectWithoutOptionalProperties({
   discriminantProperty: schemas_exports8.string(),
+  discriminantPropertyNameOverride: schemas_exports8.string().optional(),
   commonProperties: schemas_exports8.list(schemas_exports8.lazyObject(() => CommonPropertyWithExample)),
   schemas: schemas_exports8.record(schemas_exports8.string(), schemas_exports8.lazy(() => SchemaWithExample2))
 }).extend(WithSdkGroupName).extend(WithNamespace).extend(WithName3).extend(WithDescription).extend(WithAvailability3).extend(WithEncoding).extend(WithSource).extend(WithTitle).extend(WithInline);
@@ -1509196,7 +1509207,7 @@ function buildOneOfTypeDeclaration({ schema: schema2, context: context2, declara
     return {
       name: schema2.nameOverride ?? schema2.generatedName,
       schema: {
-        discriminant: schema2.discriminantProperty,
+        discriminant: schema2.discriminantPropertyNameOverride != null ? { name: schema2.discriminantPropertyNameOverride, value: schema2.discriminantProperty } : schema2.discriminantProperty,
         "base-properties": baseProperties,
         docs: schema2.description ?? void 0,
         availability: schema2.availability != null ? convertAvailability2(schema2.availability) : void 0,
@@ -1514290,6 +1514301,7 @@ function convertAvailability3(propertySchema) {
 // ../api-importers/openapi/openapi-ir-parser/lib/schema/convertDiscriminatedOneOf.js
 function convertDiscriminatedOneOf({ nameOverride, generatedName, title: title5, breadcrumbs, properties: properties7, description, availability, required: required5, wrapAsOptional, wrapAsNullable, discriminator, context: context2, namespace, groupName, encoding, source: source2 }) {
   const discriminant8 = discriminator.propertyName;
+  const discriminantNameOverride = getExtension(discriminator, FernOpenAPIExtension.FERN_PROPERTY_NAME);
   const unionSubTypes = Object.fromEntries(Object.entries(discriminator.mapping ?? {}).map(([discriminantValue, schema2]) => {
     const subtypeReference = convertReferenceObject({
       $ref: schema2
@@ -1514320,6 +1514332,7 @@ function convertDiscriminatedOneOf({ nameOverride, generatedName, title: title5,
     description,
     availability,
     discriminant: discriminant8,
+    discriminantNameOverride,
     subtypes: unionSubTypes,
     namespace,
     groupName,
@@ -1514358,17 +1514371,19 @@ function convertDiscriminatedOneOfWithVariants({ nameOverride, generatedName, ti
     description,
     availability,
     discriminant: discriminant8,
+    discriminantNameOverride: void 0,
     subtypes: unionSubTypes,
     namespace,
     groupName,
     source: source2
   });
 }
-function wrapDiscriminatedOneOf({ nameOverride, generatedName, title: title5, wrapAsOptional, wrapAsNullable, properties: properties7, description, availability, discriminant: discriminant8, subtypes, namespace, groupName, source: source2 }) {
+function wrapDiscriminatedOneOf({ nameOverride, generatedName, title: title5, wrapAsOptional, wrapAsNullable, properties: properties7, description, availability, discriminant: discriminant8, discriminantNameOverride, subtypes, namespace, groupName, source: source2 }) {
   let result = SchemaWithExample.oneOf(OneOfSchemaWithExample.discriminated({
     description,
     availability,
     discriminantProperty: discriminant8,
+    discriminantPropertyNameOverride: discriminantNameOverride,
     nameOverride,
     generatedName,
     title: title5,
@@ -1515045,6 +1515060,7 @@ function convertToOneOf(oneOfSchema) {
         description: oneOfSchema.description,
         availability: oneOfSchema.availability,
         discriminantProperty: oneOfSchema.discriminantProperty,
+        discriminantPropertyNameOverride: oneOfSchema.discriminantPropertyNameOverride,
         generatedName: oneOfSchema.generatedName,
         title: oneOfSchema.title,
         nameOverride: oneOfSchema.nameOverride,
@@ -1518255,6 +1518271,7 @@ function convertToOneOf2(oneOfSchema) {
         description: oneOfSchema.description,
         availability: oneOfSchema.availability,
         discriminantProperty: oneOfSchema.discriminantProperty,
+        discriminantPropertyNameOverride: oneOfSchema.discriminantPropertyNameOverride,
         generatedName: oneOfSchema.generatedName,
         nameOverride: oneOfSchema.nameOverride,
         title: oneOfSchema.title,
@@ -1542670,6 +1542687,16 @@ var properties4 = {
       }
     ]
   },
+  "ai-examples": {
+    oneOf: [
+      {
+        $ref: "#/definitions/docs.AiExamplesConfig"
+      },
+      {
+        type: "null"
+      }
+    ]
+  },
   metadata: {
     oneOf: [
       {
@@ -1544027,6 +1544054,16 @@ var definitions4 = {
   "docs.PlaygroundSettings": {
     type: "object",
     properties: {
+      hidden: {
+        oneOf: [
+          {
+            type: "boolean"
+          },
+          {
+            type: "null"
+          }
+        ]
+      },
       environments: {
         oneOf: [
           {
@@ -1546386,6 +1546423,32 @@ var definitions4 = {
     },
     additionalProperties: false
   },
+  "docs.AiExamplesConfig": {
+    type: "object",
+    properties: {
+      enabled: {
+        oneOf: [
+          {
+            type: "boolean"
+          },
+          {
+            type: "null"
+          }
+        ]
+      },
+      style: {
+        oneOf: [
+          {
+            type: "string"
+          },
+          {
+            type: "null"
+          }
+        ]
+      }
+    },
+    additionalProperties: false
+  },
   "docs.TwitterCardSetting": {
     type: "string",
     enum: [
@@ -1579076,7 +1579139,6 @@ var ConcurrentEndpointProcessor = class {
     return { ...this.stats };
   }
 };
-var hasLoggedInfoMessage = false;
 function isOpenApiSpec(specContent) {
   try {
     try {
@@ -1579168,17 +1579230,6 @@ async function enhanceExamplesWithAI(apiDefinition, config2, context2, token, or
   }
 }
 async function performAIEnhancement(apiDefinition, config2, context2, token, organizationId, sourceFilePath, apiName) {
-  if (!hasLoggedInfoMessage) {
-    const message = source_default.blue("Notice: new feature added (experimental)!\n\n") + "We are generating realistic examples for endpoints in your spec.\nThis will not override your current examples. Please wait a moment.\n\nFuture runs will use saved examples. If you wish to override the content of the\nexamples, please edit and commit auto-generated `ai_examples_override.yml` files.";
-    const boxedMessage = boxen(message, {
-      padding: 1,
-      textAlignment: "left",
-      borderColor: "blue",
-      borderStyle: "round"
-    });
-    context2.logger.info("\n" + boxedMessage + "\n");
-    hasLoggedInfoMessage = true;
-  }
   const enhancer = new LambdaExampleEnhancer(config2, context2, token, organizationId);
   const circuitBreaker = new CircuitBreaker();
   let openApiSpec;
@@ -1582462,7 +1582513,7 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
       link: async (value) => this.toLinkNode(value),
       changelog: async (value) => this.toChangelogNode(value, parentSlug),
       // Library sections are handled by FDR during registration, returning placeholder
-      pythonDocsSection: async () => this.toPythonDocsSectionPlaceholder(parentSlug)
+      pythonDocsSection: async (value) => this.toPythonDocsSectionPlaceholder(value, parentSlug)
     });
   }
   async toNavigationChild({ prefix: prefix2, item, parentSlug, hideChildren, parentAvailability }) {
@@ -1582473,7 +1582524,7 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
       link: async (value) => this.toLinkNode(value),
       changelog: async (value) => this.toChangelogNode(value, parentSlug, hideChildren),
       // Library sections are handled by FDR during registration, returning placeholder
-      pythonDocsSection: async () => this.toPythonDocsSectionPlaceholder(parentSlug)
+      pythonDocsSection: async (value) => this.toPythonDocsSectionPlaceholder(value, parentSlug)
     });
   }
   async toApiSectionNode({ item, parentSlug, hideChildren, parentAvailability }) {
@@ -1582591,28 +1582642,72 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
    * The CLI starts the generation job, polls for completion, and passes the jobId to FDR.
    * FDR then merges the generated Python docs into the navigation.
    *
-   * This placeholder returns a hidden section that will be replaced/augmented by FDR.
+   * In dev mode (fern docs dev), this placeholder returns a visible page with helpful content
+   * explaining that Python library docs are only generated during `fern generate --docs`.
+   *
+   * In production mode, FDR replaces/augments this with the actual generated documentation.
    */
-  toPythonDocsSectionPlaceholder(parentSlug) {
-    const slug = parentSlug.apply({ urlSlug: "python-docs", skipUrlSlug: true });
+  toPythonDocsSectionPlaceholder(item, parentSlug) {
+    const title5 = item.title ?? "Python Reference";
+    const urlSlug = item.slug ?? "python-docs";
+    const slug = parentSlug.apply({ urlSlug });
+    const syntheticPageId = `__python-docs-placeholder-${urlSlug}__.mdx`;
+    const pageId = navigation_exports2.PageId(syntheticPageId);
+    const placeholderMarkdown = `---
+title: ${title5}
+---
+
+<Warning>
+Python library documentation is not yet supported with \`fern docs dev\`. This feature will be added in a future release. To view the generated documentation, run \`fern generate --docs --preview\`.
+</Warning>
+
+## About Python Library Docs
+
+When you publish your documentation using \`fern generate --docs\`, Fern will:
+
+1. Clone and analyze your Python repository from: \`${item.githubUrl}\`
+2. Parse the Python source code to extract docstrings and type information
+3. Generate comprehensive API reference documentation
+4. Integrate the generated docs into your documentation site
+
+## How to Generate
+
+To generate the full Python library documentation, run:
+
+\`\`\`bash
+fern generate --docs
+\`\`\`
+
+Or to preview without publishing:
+
+\`\`\`bash
+fern generate --docs --preview
+\`\`\`
+
+The generated documentation will replace this placeholder page with complete API reference content including:
+
+- Module and package documentation
+- Class and function references
+- Type annotations and signatures
+- Docstring content
+`;
+    this.parsedDocsConfig.pages[RelativeFilePath2.of(syntheticPageId)] = placeholderMarkdown;
+    const id2 = this.#idgen.get(pageId);
     return {
-      type: "section",
-      id: this.#idgen.get("python-docs-placeholder"),
+      id: id2,
+      type: "page",
       slug: slug.get(),
-      title: "Python Reference",
-      collapsed: false,
-      hidden: true,
-      // Hidden - actual content comes from FDR
-      children: [],
-      overviewPageId: void 0,
+      title: title5,
       icon: void 0,
+      hidden: false,
       viewers: void 0,
       orphaned: void 0,
+      pageId,
       authed: void 0,
-      pointsTo: void 0,
-      availability: void 0,
+      noindex: true,
+      // Don't index placeholder pages
       featureFlags: void 0,
-      noindex: void 0
+      availability: void 0
     };
   }
   async toPageNode({ item, parentSlug, hideChildren, parentAvailability }) {
@@ -1591635,7 +1591730,7 @@ var import_path37 = __toESM(require("path"), 1);
 var LOCAL_STORAGE_FOLDER4 = ".fern-dev";
 var LOGS_FOLDER_NAME = "logs";
 function getCliSource() {
-  const version6 = "3.40.1";
+  const version6 = "3.42.0";
   return `cli@${version6}`;
 }
 var DebugLogger = class {
@@ -1595107,6 +1595202,16 @@ var definitions5 = {
   "docs.PlaygroundSettings": {
     type: "object",
     properties: {
+      hidden: {
+        oneOf: [
+          {
+            type: "boolean"
+          },
+          {
+            type: "null"
+          }
+        ]
+      },
       environments: {
         oneOf: [
           {
@@ -1596934,6 +1597039,16 @@ var definitions6 = {
   "docs.PlaygroundSettings": {
     type: "object",
     properties: {
+      hidden: {
+        oneOf: [
+          {
+            type: "boolean"
+          },
+          {
+            type: "null"
+          }
+        ]
+      },
       environments: {
         oneOf: [
           {
@@ -1598394,6 +1598509,14 @@ async function visitDocsConfigFileYamlAst({ contents, visitor, absoluteFilepathT
     analytics: noop2,
     aiChat: noop2,
     aiSearch: noop2,
+    aiExamples: async (aiExamples) => {
+      if (aiExamples != null && typeof aiExamples === "object") {
+        await visitObjectAsync(aiExamples, {
+          enabled: noop2,
+          style: noop2
+        });
+      }
+    },
     pageActions: noop2,
     announcement: noop2,
     backgroundImage: async (background) => {
@@ -1626826,7 +1626949,7 @@ async function publishDocs({ token, organization, docsWorkspace, domain: domain2
     },
     registerApi: async ({ ir: ir14, snippetsConfig, playgroundConfig, apiName, workspace }) => {
       let apiDefinition = convertIrToFdrApi({ ir: ir14, snippetsConfig, playgroundConfig, context: context2 });
-      const aiEnhancerConfig = getAIEnhancerConfig(withAiExamples, docsWorkspace.config.experimental?.aiExampleStyleInstructions);
+      const aiEnhancerConfig = getAIEnhancerConfig(withAiExamples, docsWorkspace.config.aiExamples?.style ?? docsWorkspace.config.experimental?.aiExampleStyleInstructions);
       if (aiEnhancerConfig && workspace) {
         const sources = workspace.getSources();
         const openApiSource = sources.find((source2) => source2.type === "openapi");
@@ -1627566,7 +1627689,7 @@ async function runRemoteGenerationForDocsWorkspace({ organization, apiWorkspaces
       isPrivate: maybeInstance.private,
       disableTemplates,
       skipUpload,
-      withAiExamples: docsWorkspace.config.experimental?.aiExamples ?? true,
+      withAiExamples: docsWorkspace.config.aiExamples?.enabled ?? docsWorkspace.config.experimental?.aiExamples ?? true,
       targetAudiences: maybeInstance.audiences ? Array.isArray(maybeInstance.audiences) ? maybeInstance.audiences : [maybeInstance.audiences] : void 0
     });
     const publishTime = performance.now() - publishStart;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.40.1",
+  "version": "3.42.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fern-api/fern.git",