@stainless-api/docs 0.1.0-beta.93 → 0.1.0-beta.95

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.95
+
+### Minor Changes
+
+- 6b86a8b: Support multiple snippet examples
+
+### Patch Changes
+
+- Updated dependencies [6b86a8b]
+  - @stainless-api/docs-ui@0.1.0-beta.72
+  - @stainless-api/docs-search@0.1.0-beta.25
+
+## 0.1.0-beta.94
+
+### Minor Changes
+
+- beff534: Adds support for multiple sdkjsons
+
+### Patch Changes
+
+- Updated dependencies [cd578b7]
+- Updated dependencies [beff534]
+  - @stainless-api/docs-ui@0.1.0-beta.71
+  - @stainless-api/docs-search@0.1.0-beta.24
+
 ## 0.1.0-beta.93
 
 ### Patch Changes

package/eslint-suppressions.json

@@ -1,9 +1,4 @@
 {
-  "plugin/buildAlgoliaIndex.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 2
-    }
-  },
   "plugin/components/SnippetCode.tsx": {
     "@typescript-eslint/no-explicit-any": {
       "count": 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.93",
+  "version": "0.1.0-beta.95",
   "publishConfig": {
     "access": "public"
   },
@@ -56,8 +56,8 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-search": "0.1.0-beta.23",
-    "@stainless-api/docs-ui": "0.1.0-beta.70",
+    "@stainless-api/docs-search": "0.1.0-beta.25",
+    "@stainless-api/docs-ui": "0.1.0-beta.72",
     "@stainless-api/ui-primitives": "0.1.0-beta.47"
   },
   "devDependencies": {
@@ -73,7 +73,7 @@
     "vite": "^6.4.1",
     "zod": "^4.3.5",
     "@stainless/eslint-config": "0.1.0-beta.1",
-    "@stainless/sdk-json": "^0.1.0-beta.4"
+    "@stainless/sdk-json": "^0.1.0-beta.5"
   },
   "scripts": {
     "vendor-deps": "tsx scripts/vendor_deps.ts",

package/plugin/buildAlgoliaIndex.ts

@@ -1,10 +1,8 @@
 import Markdoc from '@markdoc/markdoc';
-import Stainless from '@stainless-api/sdk';
-import { createSDKJSON, parseInputs, transformOAS } from './specs/worker';
-import type * as SDKJSON from '@stainless/sdk-json';
-import { Languages } from '@stainless-api/docs-ui/routing';
 import { buildIndex } from '@stainless-api/docs-search/providers/algolia';
 import type { AstroIntegrationLogger } from 'astro';
+import { generateIndex } from '@stainless-api/docs-search/indexer';
+import { SpecComposite } from './specs';
 
 const markdocConfig = {
   nodes: {
@@ -21,14 +19,10 @@ function renderMarkdown(content?: string) {
 }
 
 export async function buildAlgoliaIndex({
-  stainlessProject,
-  branch,
-  apiKey,
+  specComposite,
   logger,
 }: {
-  stainlessProject: string;
-  branch: string;
-  apiKey: string;
+  specComposite: SpecComposite;
   logger?: AstroIntegrationLogger;
 }) {
   function warnLog(message: string) {
@@ -47,38 +41,6 @@ export async function buildAlgoliaIndex({
     }
   }
 
-  // TODO: this is all redundant with the spec code and should be DRYed
-  const client = new Stainless({ apiKey });
-  const configs = await client.projects.configs.retrieve({
-    project: stainlessProject,
-    branch,
-    include: 'openapi',
-  });
-
-  const configYML = Object.values(configs)[0] as { content: any };
-  const oasJson = Object.values(configs)[1] as { content: any };
-  const configStr = configYML['content'];
-  const oasStr = oasJson['content'];
-  const { oas, config } = await parseInputs({
-    oas: oasStr,
-    config: configStr,
-  });
-
-  const transformedOAS = await transformOAS({ oas, config });
-
-  const languages =
-    config.docs?.languages ??
-    (Object.entries(config.targets)
-      .filter(([name, target]) => Languages.includes(name) && !target.skip)
-      .map(([name]) => name) as SDKJSON.SpecLanguage[]);
-
-  const sdkJson = await createSDKJSON({
-    oas: transformedOAS,
-    config,
-    languages,
-    projectName: stainlessProject,
-  });
-
   const {
     PUBLIC_ALGOLIA_APP_ID: appId,
     PUBLIC_ALGOLIA_INDEX: indexName,
@@ -94,6 +56,13 @@ export async function buildAlgoliaIndex({
     warnLog(`Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
     return;
   }
-  await buildIndex(appId, indexName, algoliaWriteKey, sdkJson, renderMarkdown);
+
+  const indexEntries = specComposite
+    .listUniqueSpecs()
+    .flatMap((spec) =>
+      Array.from(generateIndex(spec.data.sdkJson, renderMarkdown, true, spec.data.languages)),
+    );
+
+  await buildIndex(appId, indexName, algoliaWriteKey, indexEntries, renderMarkdown);
   infoLog('Indexing complete.');
 }

package/plugin/components/SDKSelect.astro

@@ -1,10 +1,9 @@
 ---
 import { parseRoute } from '@stainless-api/docs-ui/routing';
-import { DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { DEFAULT_LANGUAGE } from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';
 import { SDKSelectReactComponent } from '../react/Routing';
-import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
-import { getDocsLanguages } from '../helpers/getDocsLanguages';
+import { getDocsLanguages } from '../helpers/multiSpec';
 import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
 
 const slug = `/${Astro.locals.starlightRoute.id}`;
@@ -20,9 +19,7 @@ const data = {
   defaultLanguage,
 };
 
-const spec = await getSDKJSONInSSR();
-
-const options = getDocsLanguages(spec, EXCLUDE_LANGUAGES).map((value) => ({
+const options = getDocsLanguages().map((value) => ({
   value,
   label: Languages[value].name,
   selected: data.language === value,

package/plugin/globalJs/code-snippets.ts

@@ -19,9 +19,10 @@ document.addEventListener(getPageLoadEvent(), () => {
       document
         .querySelectorAll(`[data-snippet-response-pane-id="${panelId}"]`)
         .forEach((p) => p.classList.add('stldocs-snippet-response-pane-active'));
-      document
-        .querySelectorAll(`[data-snippet-response-tab-id="${panelId}"]`)
-        .forEach((p) => p.classList.add('stldocs-snippet-response-tab-item-active'));
+      document.querySelectorAll(`[data-snippet-response-tab-id="${panelId}"]`).forEach((p) => {
+        p.classList.add('stldocs-snippet-response-tab-item-active');
+        p.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'center' });
+      });
     });
   });
 
@@ -91,4 +92,25 @@ document.addEventListener(getPageLoadEvent(), () => {
       btn.textContent = 'Show more';
     }
   });
+
+  document.querySelectorAll('[data-stldocs-multi-snippet-container]').forEach((container) => {
+    const radios = container.querySelectorAll<HTMLInputElement>('input[type="radio"]');
+    const panes = container.querySelectorAll<HTMLDivElement>('[data-stldocs-multi-snippet-id]');
+
+    radios.forEach((radio) => {
+      radio.addEventListener('change', (e) => {
+        if (!(e.target instanceof HTMLInputElement)) return;
+        if (e.target.checked) {
+          const selectedIndex = e.target.value;
+          panes.forEach((pane) => {
+            pane.classList.toggle(
+              'stldocs-snippet-multi-pane-active',
+              pane.dataset.stldocsMultiSnippetId === selectedIndex,
+            );
+          });
+          e.target.parentElement?.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'center' });
+        }
+      });
+    });
+  });
 });

package/plugin/globalJs/copy.ts

@@ -92,7 +92,8 @@ function loadPlayground(playButton: HTMLElement) {
       doc: (language === 'python' ? 'from rich import print\n' : '') + code.trimEnd(),
       container,
       onLanguageSelect: (value) => {
-        const originalLanguage = document.getElementById('stldocs-snippet-select')?.dataset.currentValue;
+        const originalLanguage = container.querySelector<HTMLElement>('[data-stldocs-snippet-select]')
+          ?.dataset.currentValue;
         const path: string = updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value);
         navigate(path.replace(/(\?.+)?($|#)/, (_, str, end) => (str ? str + '&play' : '?play') + end));
       },

package/plugin/globalJs/navigation.ts

@@ -22,15 +22,14 @@ window.addEventListener('popstate', (ev: PopStateEvent) => {
 });
 
 document.addEventListener(getPageLoadEvent(), () => {
-  const rootElement = document.getElementById('stldocs-snippet-select');
-  if (!rootElement) return;
-
-  initDropdown({
-    root: rootElement,
-    onSelect: (value) => {
-      const originalLanguage = rootElement?.dataset.currentValue;
-      navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
-    },
+  document.querySelectorAll<HTMLElement>('[data-stldocs-snippet-select]').forEach((rootElement) => {
+    initDropdown({
+      root: rootElement,
+      onSelect: (value) => {
+        const originalLanguage = rootElement.dataset.currentValue;
+        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
+      },
+    });
   });
 
   const path = getStainlessPathForLocation();

package/plugin/helpers/generateDocsRoutes.ts

@@ -1,6 +1,8 @@
 import type * as SDKJSON from '@stainless/sdk-json';
 import { DocsLanguage, generateRouteList } from '@stainless-api/docs-ui/routing';
 import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { api } from 'virtual:stainless-apis-manifest';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
 
 export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLanguage[] = EXCLUDE_LANGUAGES) {
   const paths = generateRouteList({
@@ -25,3 +27,33 @@ export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLan
     };
   });
 }
+
+export async function generateAllDocsRoutes() {
+  const uniquePaths = new Set<string>();
+
+  const allRoutes = (
+    await Promise.all(
+      api.languages.map(async (entry) => {
+        const spec = await getSDKJSONInSSR(entry.language);
+
+        // this is super annoying, but preview worker _always_ generates HTTP routes
+        // so, we exclude them unless the we're explicitly told to include them
+        const excludeLanguages = [...EXCLUDE_LANGUAGES];
+        if (entry.language !== 'http') {
+          excludeLanguages.push('http');
+        }
+
+        const routes = generateDocsRoutes(spec, excludeLanguages);
+        return routes.filter((route) => {
+          if (uniquePaths.has(route.params.slug)) {
+            return false;
+          }
+          uniquePaths.add(route.params.slug);
+          return true;
+        });
+      }),
+    )
+  ).flat();
+
+  return allRoutes;
+}

package/plugin/helpers/multiSpec.ts

@@ -0,0 +1,8 @@
+import { api } from 'virtual:stainless-apis-manifest';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+
+export function getDocsLanguages() {
+  return api.languages
+    .map((language) => language.language)
+    .filter((language) => !EXCLUDE_LANGUAGES.includes(language));
+}

package/plugin/index.ts

@@ -3,7 +3,7 @@ import type { StarlightPlugin } from '@astrojs/starlight/types';
 import type { AstroIntegration } from 'astro';
 import type { BundledTheme } from 'shiki';
 import { config } from 'dotenv';
-import { buildAlgoliaIndex } from './buildAlgoliaIndex';
+// import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import {
   getAPIReferencePlaceholderItemFromSidebarConfig,
   makePlaceholderItems,
@@ -32,8 +32,8 @@ import prebundleWorkers from 'vite-plugin-prebundle-workers';
 import { SpecLoader, startSpecLoader } from './specs';
 
 import type * as ReferenceSidebarsVirtualModule from 'virtual:stl-starlight-reference-sidebars';
-import { getDocsLanguages } from './helpers/getDocsLanguages';
 import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
+import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
@@ -102,13 +102,10 @@ async function stlStarlightAstroIntegration(
   let astroBase = '/';
 
   let specLoader: SpecLoader | undefined;
-  async function getSpec() {
+  async function resolveSpecs() {
     if (!specLoader) throw new Error('Expected spec loader to exist');
     const result = await specLoader.specPromise;
-    return {
-      spec: result.spec.data,
-      auth: result.spec.auth,
-    };
+    return result.specComposite;
   }
 
   let building: Promise<void> | undefined;
@@ -119,9 +116,16 @@ async function stlStarlightAstroIntegration(
     if (!pluginConfig.experimentalPlaygrounds) return;
     if (building) return building;
     return (building = (async () => {
-      const { spec, auth } = await getSpec();
+      const specComposite = await resolveSpecs();
+
+      if (specComposite.listUniqueSpecs().length > 1) {
+        throw new Error('Multiple specs found. This is not supported for Playgrounds.');
+      }
 
-      const langs = getDocsLanguages(spec, pluginConfig.excludeLanguages);
+      const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+      const auth = specComposite.listUniqueSpecs()[0]!.data.auth;
+
+      const langs = specComposite.getLanguages();
 
       await buildPlaygrounds!({
         spec,
@@ -150,14 +154,9 @@ async function stlStarlightAstroIntegration(
         const projectDir = astroConfig.root.pathname;
         astroBase = astroConfig.base;
 
+        logger.warn('Starting spec loader!!!');
+
         specLoader = await startSpecLoader(pluginConfig, logger, createCodegenDir());
-        specLoader.specPromise.then((specResult) => {
-          if (specResult.result === 'generated') {
-            logger.info(`Generated new SDKJSON`);
-          } else if (specResult.result === 'exists') {
-            logger.info(`Loaded SDKJSON`);
-          }
-        });
 
         reportError = (message: string) => logger.error(message);
 
@@ -198,22 +197,23 @@ async function stlStarlightAstroIntegration(
               makeAsyncVirtualModPlugin<typeof ReferenceSidebarsVirtualModule>(
                 'virtual:stl-starlight-reference-sidebars',
                 async () => {
-                  const { spec } = await getSpec();
-                  const languages = getDocsLanguages(spec, pluginConfig.excludeLanguages);
+                  // we know specLoader exists here
+                  const { specComposite } = await specLoader!.specPromise;
 
                   const sidebars = [...sidebarConfigs.entries()]
                     // produce all { id, language } combos with the attached config
                     // flattens to one item per language * id combo
                     .flatMap(([id, config]) =>
-                      languages.map((language) => ({
+                      specComposite.listAllLanguagesAndIncludeSpecs().map((res) => ({
                         id,
                         config,
-                        language,
+                        language: res.language,
+                        spec: res.spec.data.sdkJson,
                       })),
                     )
                     // produce a sidebar for each
                     // later we will .find() the sidebar that matches the (id, language)
-                    .map(({ id, config, language }) => {
+                    .map(({ id, config, language, spec }) => {
                       const configItemsBuilder = new SidebarConfigItemsBuilder(
                         spec,
                         language,
@@ -232,7 +232,7 @@ async function stlStarlightAstroIntegration(
                         // this has to run multpile times because it depends on the
                         // userSidebarConfig (which is per-id) and the language
                         entries: toStarlightSidebar({
-                          basePath: path.posix.join(astroBase, pluginConfig.basePath), // TODO, is this right?
+                          basePath: path.posix.join(astroBase, pluginConfig.basePath),
                           spec,
                           entries: userSidebarConfig,
                           currentLanguage: language,
@@ -243,7 +243,7 @@ async function stlStarlightAstroIntegration(
                   return { sidebars };
                 },
               ),
-              specLoader.vitePlugin,
+              ...specLoader.vitePlugins,
               {
                 name: 'stl-starlight-vite',
                 buildStart() {
@@ -314,7 +314,7 @@ async function stlStarlightAstroIntegration(
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
                         EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
                         EXPERIMENTAL_REQUEST_BUILDER: pluginConfig.experimentalRequestBuilder,
-                        STAINLESS_PROJECT: pluginConfig.specInputs.project,
+                        STAINLESS_PROJECT: pluginConfig.stainlessProject,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
@@ -363,12 +363,22 @@ async function stlStarlightAstroIntegration(
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
 
+        const specComposite = await resolveSpecs();
+
+        await buildAlgoliaIndex({
+          specComposite,
+          logger,
+        });
+
         // Generate a list of missing API routes to enable graceful handling of unimplemented SDK methods.
         // When users switch languages in the docs, some API methods may not be implemented in the target SDK.
         // Instead of showing a generic 404, we statically generate pages for these routes and mark them
         // in this file so Cloudflare can serve them with a 404 status. These pages display helpful information
         // about the missing method and provide links to SDKs where it is available.
-        const { spec } = await getSpec();
+
+        // TODO: (multi-spec) support multiple specs
+        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+
         const missingRoutes = generateMissingRouteList({
           spec,
           basePath: path.posix.join(astroBase, pluginConfig.basePath),
@@ -402,7 +412,10 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 
         const logger = getSharedLogger({ fallback: localLogger });
 
-        const configParseResult = parseStarlightPluginConfig(someUserConfig, command);
+        const configParseResult = parseStarlightPluginConfig(someUserConfig, {
+          command,
+          base: astroConfig.base,
+        });
         if (configParseResult.result === 'error') {
           const errorLines = configParseResult.message.split('\n');
           for (const line of errorLines) {
@@ -419,26 +432,18 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           addIntegration(react());
         }
 
-        if ('apiKey' in config.specInputs) {
-          if (!config.specInputs.apiKey) {
-            logger.info(`Stainless credentials not loaded`);
-          } else if (config.specInputs.apiKey.source === 'explicit-config') {
-            logger.info(`Stainless credentials loaded from user config`);
-          } else if (config.specInputs.apiKey.source === 'environment-variable') {
-            logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
-          } else if (config.specInputs.apiKey.source === 'cli') {
-            logger.info('Stainless credentials loaded from `stl` CLI');
-          }
-        }
-
-        if (command === 'build' && config.specInputs.kind === 'stainless_api_inputs') {
-          await buildAlgoliaIndex({
-            stainlessProject: config.specInputs.project,
-            branch: config.specInputs.branch,
-            apiKey: config.specInputs.apiKey.value,
-            logger,
-          });
-        }
+        // TODO: (multi-spec) re-add this? not strictly necessary to merge
+        // if ('apiKey' in config.specInputs) {
+        //   if (!config.specInputs.apiKey) {
+        //     logger.info(`Stainless credentials not loaded`);
+        //   } else if (config.specInputs.apiKey.source === 'explicit-config') {
+        //     logger.info(`Stainless credentials loaded from user config`);
+        //   } else if (config.specInputs.apiKey.source === 'environment-variable') {
+        //     logger.info('Stainless credentials loaded from `STAINLESS_API_KEY` environment variable');
+        //   } else if (config.specInputs.apiKey.source === 'cli') {
+        //     logger.info('Stainless credentials loaded from `stl` CLI');
+        //   }
+        // })
 
         if (starlightConfig.sidebar) {
           // for pagination (https://starlight.astro.build/reference/configuration/#pagination) to work correctly
@@ -483,3 +488,5 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 // Additional exports we want for Stainless <-> docs integration.
 export { parseStainlessPath } from '@stainless-api/docs-ui/routing';
 export { renderMarkdown } from '@stainless-api/docs-ui/markdown';
+
+export { resolveSpec } from './specs/inputResolver';