@stainless-api/docs 0.1.0-beta.73 → 0.1.0-beta.75

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.75
+
+### Patch Changes
+
+- b1ff7b3: write manifest file after build
+
+## 0.1.0-beta.74
+
+### Patch Changes
+
+- d0d1122: support astro config base param
+- Updated dependencies [6eb6d38]
+- Updated dependencies [7bc8f4e]
+- Updated dependencies [2f6b86d]
+  - @stainless-api/docs-ui@0.1.0-beta.57
+  - @stainless-api/ui-primitives@0.1.0-beta.43
+  - @stainless-api/docs-search@0.1.0-beta.10
+
 ## 0.1.0-beta.73
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.73",
+  "version": "0.1.0-beta.75",
   "publishConfig": {
     "access": "public"
   },
@@ -58,9 +58,9 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-search": "0.1.0-beta.9",
-    "@stainless-api/docs-ui": "0.1.0-beta.56",
-    "@stainless-api/ui-primitives": "0.1.0-beta.42"
+    "@stainless-api/docs-search": "0.1.0-beta.10",
+    "@stainless-api/docs-ui": "0.1.0-beta.57",
+    "@stainless-api/ui-primitives": "0.1.0-beta.43"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",

package/plugin/cms/server.ts

@@ -300,7 +300,6 @@ export function startDevServer({
             userSidebarConfig = transformedSidebarConfig;
           }
         }
-
         const starlightSidebar = toStarlightSidebar({
           basePath: body.basePath,
           currentSlug: body.currentSlug,

package/plugin/globalJs/copy.ts

@@ -1,5 +1,7 @@
-import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import { BASE_PATH, EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
+import { updateSelectedLanguage } from '../languages';
+import { navigate } from 'astro/virtual-modules/transitions-router.js';
 const copyIcon = `<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>`;
 const circleAlertIcon = `<circle cx="12" cy="12" r="10"/><line x1="12" x2="12" y1="8" y2="12"/><line x1="12" x2="12.01" y1="16" y2="16"/>`;
 const checkIcon = `<path d="M20 6 9 17l-5-5"/>`;
@@ -80,11 +82,18 @@ function loadPlayground(playButton: HTMLElement) {
       await import(/* @vite-ignore */ id).catch(console.warn);
     }
     const { createPlayground } = await import('virtual:stl-playground/create');
+    const { default: playgroundData } = await import('virtual:stl-playground/data');
     return createPlayground({
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       lang: language as any,
       doc: (language === 'python' ? 'from rich import print\n' : '') + code.trimEnd(),
       container,
+      onLanguageSelect: (value) => {
+        const originalLanguage = document.getElementById('stldocs-snippet-select')?.dataset.currentValue;
+        const path: string = updateSelectedLanguage(BASE_PATH, originalLanguage, value);
+        navigate(path.replace(/(\?.+)?($|#)/, (_, str, end) => (str ? str + '&play' : '?play') + end));
+      },
+      ...playgroundData,
     });
   })();
   return async () => {

package/plugin/globalJs/playground-data.shim.ts

@@ -0,0 +1 @@
+export default {};

package/plugin/globalJs/playground-data.ts

@@ -0,0 +1,14 @@
+import wheelUrl from 'virtual:stl-playground/python/wheel.whl?url';
+import pyTypes from 'virtual:stl-playground/python.json';
+import tsTypes from 'virtual:stl-playground/typescript.json';
+import authData from 'virtual:stl-playground/auth.json';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { Config } from 'virtual:stl-playground/create';
+
+export default {
+  wheelUrl,
+  pyTypes,
+  tsTypes,
+  authData,
+  HIGHLIGHT_THEMES,
+} satisfies Config;

package/plugin/index.ts

@@ -27,7 +27,7 @@ import path from 'path';
 import fs from 'fs';
 import { getSharedLogger } from '../shared/getSharedLogger';
 import { resolveSrcFile } from '../resolveSrcFile';
-import { mkdir } from 'fs/promises';
+import { mkdir, writeFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import prebundleWorkers from 'vite-plugin-prebundle-workers';
 
@@ -124,6 +124,7 @@ async function stlStarlightAstroIntegration(
   const resolvedId = `\0${virtualId}`;
   let playgroundsBase: string | undefined;
   let buildPlaygrounds;
+  let astroBase = '/';
 
   const CMS_PORT = await getPort();
 
@@ -188,6 +189,7 @@ async function stlStarlightAstroIntegration(
       }) => {
         const logger = getSharedLogger({ fallback: localLogger });
         const projectDir = astroConfig.root.pathname;
+        astroBase = astroConfig.base;
 
         reportError = (message: string) => logger.error(message);
 
@@ -266,7 +268,17 @@ async function stlStarlightAstroIntegration(
                       new URL(
                         pluginConfig.experimentalPlaygrounds
                           ? path.join(playgroundsBase!, '/src/create.tsx')
-                          : './create-playground.shim.tsx',
+                          : './globalJs/create-playground.shim.ts',
+                        import.meta.url,
+                      ),
+                    );
+                  }
+                  if (id === 'virtual:stl-playground/data') {
+                    return fileURLToPath(
+                      new URL(
+                        pluginConfig.experimentalPlaygrounds
+                          ? './globalJs/playground-data.ts'
+                          : './globalJs/playground-data.shim.ts',
                         import.meta.url,
                       ),
                     );
@@ -287,7 +299,7 @@ async function stlStarlightAstroIntegration(
                   if (id === resolvedId) {
                     return [
                       buildVirtualModuleString({
-                        BASE_PATH: pluginConfig.basePath,
+                        BASE_PATH: path.posix.join(astroConfig.base, pluginConfig.basePath),
                         CMS_PORT,
                         EXCLUDE_LANGUAGES: ['php', ...pluginConfig.excludeLanguages],
                         DEFAULT_LANGUAGE: pluginConfig.defaultLanguage,
@@ -301,6 +313,7 @@ async function stlStarlightAstroIntegration(
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
                         EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
+                        STAINLESS_PROJECT: version.stainlessProject,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
@@ -346,6 +359,11 @@ async function stlStarlightAstroIntegration(
           }
           collectedErrors = null;
         }
+
+        const manifest = {
+          astroBase,
+        };
+        await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
       },
     },
   };

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -6,14 +6,14 @@ import { getAPIReferencePlaceholderItems } from './referencePlaceholderUtils';
 import { getMethodFromSDKJSON, recursiveReplacePlaceholderItems } from './generateAPIReferenceLink';
 import { forceGenerateRoute } from './cms/sidebar-builder';
 import { parseRoute } from '@stainless-api/docs-ui/routing';
+import path from 'path';
 
 // this fn is loaded in the plugin via addRouteMiddleware
 
 export const onRequest = defineRouteMiddleware(async (context) => {
   // if using content collection schema, use: context.locals.starlightRoute.entry.data.stainlessStarlight
   // this worked without collections but relied on hijacking starlightRoute: context.props.frontmatter.stainlessStarlight
-
-  const slug = `/${context.locals.starlightRoute.id}`; // same as .slug but not deprecated
+  const slug = path.posix.join(import.meta.env.BASE_URL ?? '', `/${context.locals.starlightRoute.id}`); // same as .slug but not deprecated
 
   context.locals.starlightRoute._stlStarlight = {
     basePath: BASE_PATH,

package/stl-docs/index.ts

@@ -6,7 +6,7 @@ import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 import type { AstroIntegration } from 'astro';
 
 import { normalizeRedirects, type NormalizedRedirectConfig } from './redirects';
-import { join } from 'path';
+import path, { join } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import {
   parseStlDocsConfig,
@@ -149,32 +149,6 @@ function stainlessDocsIntegration(
   config: NormalizedStainlessDocsConfig,
   apiReferenceBasePath: string | null,
 ): AstroIntegration {
-  const virtualModules = new Map(
-    Object.entries({
-      'virtual:stl-docs-virtual-module': buildVirtualModuleString({
-        TABS: config.tabs,
-        SPLIT_TABS_ENABLED: config.splitTabsEnabled,
-        HEADER_LINKS: config.header.links,
-        HEADER_LAYOUT: config.header.layout,
-        ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-        API_REFERENCE_BASE_PATH: apiReferenceBasePath,
-        ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
-        ENABLE_CONTEXT_MENU: config.contextMenu, // TODO: do not duplicate this between both virtual modules
-        RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
-      } satisfies typeof StlDocsVirtualModule),
-
-      'virtual:stl-docs/components/AiChat.tsx': `
-        ${
-          config.aiChat
-            ? `export { default } from ${JSON.stringify(config.aiChat.chatComponentPath)};`
-            : // export null when no AI chat component is provided
-              `export default null;`
-        }
-        export const STAINLESS_PROJECT = ${config.apiReference ? JSON.stringify(config.apiReference.stainlessProject) : 'undefined'};
-      `,
-    }),
-  );
-
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
   const resolveVirtualModuleId = (id: string) => `\0${id}`;
   let redirects: NormalizedRedirectConfig | null = null;
@@ -189,6 +163,34 @@ function stainlessDocsIntegration(
           redirects = normalizeRedirects(astroConfig.redirects);
         }
 
+        const fullApiReferenceBasePath = path.posix.join(astroConfig.base, apiReferenceBasePath ?? '/api');
+
+        const virtualModules = new Map(
+          Object.entries({
+            'virtual:stl-docs-virtual-module': buildVirtualModuleString({
+              TABS: config.tabs,
+              SPLIT_TABS_ENABLED: config.splitTabsEnabled,
+              HEADER_LINKS: config.header.links,
+              HEADER_LAYOUT: config.header.layout,
+              ENABLE_CLIENT_ROUTER: config.enableClientRouter,
+              API_REFERENCE_BASE_PATH: fullApiReferenceBasePath,
+              ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
+              ENABLE_CONTEXT_MENU: config.contextMenu, // TODO: do not duplicate this between both virtual modules
+              RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
+            } satisfies typeof StlDocsVirtualModule),
+
+            'virtual:stl-docs/components/AiChat.tsx': `
+        ${
+          config.aiChat
+            ? `export { default } from ${JSON.stringify(config.aiChat.chatComponentPath)};`
+            : // export null when no AI chat component is provided
+              `export default null;`
+        }
+        export const STAINLESS_PROJECT = ${config.apiReference ? JSON.stringify(config.apiReference.stainlessProject) : 'undefined'};
+      `,
+          }),
+        );
+
         updateConfig({
           vite: {
             plugins: [

package/stl-docs/tabsMiddleware.ts

@@ -3,6 +3,7 @@ import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 
 import { SPLIT_TABS_ENABLED, TABS } from 'virtual:stl-docs-virtual-module';
 import clsx from 'clsx';
+import path from 'path';
 
 // this fn is loaded in the plugin via addRouteMiddleware
 
@@ -105,7 +106,7 @@ export const onRequest = defineRouteMiddleware(async (context) => {
   // if using content collection schema, use: context.locals.starlightRoute.entry.data.stainlessStarlight
   // this worked without collections but relied on hijacking starlightRoute: context.props.frontmatter.stainlessStarlight
 
-  const slug = `/${context.locals.starlightRoute.id}`; // same as .slug but not deprecated
+  const slug = path.posix.join(import.meta.env.BASE_URL ?? '', context.locals.starlightRoute.id); // same as .slug but not deprecated
 
   /*
     In the index of our starlight plugin, we transform our "tabs" into a plain old Starlight sidebar.

package/virtual-module.d.ts

@@ -1,5 +1,98 @@
+declare module 'virtual:stl-playground/typescript.json' {
+  const data: {
+    links: [string, string][];
+    files: [string, string][];
+  } | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/python.json' {
+  const data: { files: Record<string, string>; wheel: string } | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/auth.json' {
+  const data:
+    | ({
+        type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+        description?: string;
+        name: string;
+        title: string;
+        header: string | undefined;
+        example: string | undefined;
+      } & {
+        opts: {
+          name: string;
+          type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+          nullable: boolean;
+          description?: string | undefined;
+          example?: unknown;
+          default?: unknown;
+          read_env?: string | undefined;
+          auth?:
+            | {
+                security_scheme: string;
+                role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+              }
+            | undefined;
+        }[];
+      })[]
+    | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/data' {
+  import type { Config } from 'virtual:stl-playground/create';
+  declare const data: Config;
+  export { data as default };
+}
 declare module 'virtual:stl-playground/create' {
-  export const createPlayground: CreatePlayground;
+  export type PlaygroundLanguage = 'python' | 'typescript' | 'http';
+  export type Config = {
+    wheelUrl: string;
+    pyTypes: {
+      files: Record<string, string>;
+      wheel: string;
+    } | null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    HIGHLIGHT_THEMES: any;
+    tsTypes: {
+      links: [string, string][];
+      files: [string, string][];
+    } | null;
+    authData:
+      | ({
+          type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+          description?: string;
+          name: string;
+          title: string;
+          header: string | undefined;
+          example: string | undefined;
+        } & {
+          opts: {
+            name: string;
+            type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+            nullable: boolean;
+            description?: string | undefined;
+            example?: unknown;
+            default?: unknown;
+            read_env?: string | undefined;
+            auth?:
+              | {
+                  security_scheme: string;
+                  role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+                }
+              | undefined;
+          }[];
+        })[]
+      | null;
+  };
+  export function createPlayground(
+    props: {
+      lang: PlaygroundLanguage;
+      doc: string;
+      /** div.stl-snippet-request-container */
+      container: HTMLElement;
+      onLanguageSelect: (value: string) => void;
+    } & Config,
+  ): () => Promise<void>;
 }
 
 declare module 'virtual:stl-starlight-virtual-module' {
@@ -24,6 +117,7 @@ declare module 'virtual:stl-starlight-virtual-module' {
   export const PROPERTY_SETTINGS: PropertySettingsType;
   export const MIDDLEWARE: StlStarlightMiddleware;
   export const ENABLE_CONTEXT_MENU: boolean;
+  export const STAINLESS_PROJECT: string | undefined;
 }
 
 declare module 'virtual:stl-docs-virtual-module' {