@stainless-api/docs 0.1.0-beta.0

package/plugin/react/Routing.tsx

@@ -0,0 +1,435 @@
+import * as React from 'react';
+import { marked } from 'marked';
+import hljs from 'highlight.js';
+import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
+import remarkGfmAlerts from 'remark-github-alerts';
+
+import type { MarkdownHeading } from 'astro';
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+
+import {
+  generateRouteList,
+  generateRoute,
+  parseStainlessPath,
+  walkTree,
+  SupportedLanguageSyntaxes,
+  getLanguageSnippet,
+} from '@stainless-api/docs-ui/src/routing';
+
+import {
+  DocsProvider,
+  MarkdownProvider,
+  NavigationProvider,
+  useSpec,
+  type ContentPanelLayout,
+} from '@stainless-api/docs-ui/src/contexts';
+
+import { flatResources, getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+
+import {
+  SDKMethod,
+  SDKResource,
+  type SDKRequestTitleProps,
+  SDKBreadcrumbs,
+  Dropdown,
+  DropdownTrigger,
+  DropdownMenu,
+  DropdownItem,
+  SDKIcon,
+  SDKOverview,
+  SDKLanguageBlock,
+} from '@stainless-api/docs-ui/src/components';
+import {
+  BASE_PATH,
+  EXCLUDE_LANGUAGES,
+  EXPAND_RESOURCES,
+  HIGHLIGHT_THEMES,
+  BREADCRUMB_CONFIG,
+  PROPERTY_SETTINGS,
+} from 'virtual:stl-starlight-virtual-module';
+import style from '@stainless-api/docs-ui/src/style';
+import { createHighlighter, type BundledLanguage, type BundledTheme, type HighlighterGeneric } from 'shiki';
+import { SnippetCode, SnippetContainer, SnippetRequestContainer } from '../components/SnippetCode';
+import clsx from 'clsx';
+import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
+import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
+import { APIReferenceAIDropdown } from '../../stl-docs/components/APIReferenceAIDropdown';
+
+export function generateDocsRoutes(spec: SDKJSON.Spec) {
+  const paths = generateRouteList({
+    spec,
+    excludeLanguages: EXCLUDE_LANGUAGES as DocsLanguage[],
+  });
+  const readmes = Object.entries(spec.readme)
+    .filter(([language]) => language !== 'http')
+    .filter(([language]) => !EXCLUDE_LANGUAGES.includes(language as DocsLanguage))
+    .map(([language]) => ({
+      slug: language,
+      stainlessPath: null,
+      language: language as DocsLanguage,
+      title: 'Readme',
+      kind: 'readme',
+    }));
+
+  return [...paths, ...readmes].map(({ slug, stainlessPath, language, title, kind }) => {
+    return {
+      params: { slug },
+      props: { stainlessPath, language, title, kind },
+    };
+  });
+}
+
+function isResourceNonEmpty(resource: SDKJSON.Resource) {
+  return (
+    Object.keys(resource.methods ?? {}).length > 0 ||
+    Object.keys(resource.subresources ?? {}).length > 0 ||
+    Object.keys(resource.models ?? {}).length > 0
+  );
+}
+
+type SidebarEntry = StarlightRouteData['sidebar'][number];
+
+export function buildSidebar(
+  basePath: string,
+  language: DocsLanguage,
+  current: string,
+  spec: SDKJSON.Spec,
+  resources?: Record<string, SDKJSON.Resource>,
+  nested?: boolean,
+): StarlightRouteData['sidebar'] {
+  const totalRoutes = Array.from(walkTree(spec, false)).filter(
+    (item) => item.data.kind === 'http_method',
+  ).length;
+
+  return Object.values(resources ?? spec.resources ?? [])
+    .filter((resource) => isResourceNonEmpty(resource))
+    .sort((a, b) => (a.name.startsWith('$') === b.name.startsWith('$') ? 0 : a.name.startsWith('$') ? 1 : -1))
+    .map((resource) => {
+      const subs = buildSidebar(basePath, language, current, spec, resource.subresources, true);
+
+      const overview: SidebarEntry = {
+        type: 'link',
+        isCurrent: current === resource.stainlessPath,
+        attrs: { 'data-stldocs-overview': resource.name },
+        label: 'Overview',
+        href: generateRoute(basePath, language, resource.stainlessPath) ?? basePath,
+        badge: undefined,
+      };
+
+      const meths: SidebarEntry[] = Object.values(resource.methods ?? [])
+        .filter((method) => spec.decls?.[language]?.[method.stainlessPath])
+        .toSorted((first, second) => first.name.localeCompare(second.name))
+        .map((method) => ({
+          type: 'link',
+          isCurrent: current === method.stainlessPath,
+          attrs: { 'data-stldocs-method': method.httpMethod },
+          label: method.summary ?? method.name,
+          href: generateRoute(basePath, language, method.stainlessPath) ?? basePath,
+          badge: undefined,
+        }));
+
+      const shouldExpand = EXPAND_RESOURCES ?? totalRoutes < 20;
+
+      return {
+        type: 'group',
+        label: resource.title,
+        badge: undefined,
+        collapsed: !shouldExpand || nested === true,
+        entries: [...(resources ? [] : [overview]), ...meths, ...subs],
+      };
+    });
+}
+
+export function buildPageNavigation(resource: SDKJSON.Resource, depth: number = 2): MarkdownHeading[] {
+  const output: MarkdownHeading[] = [{ depth, slug: resource.stainlessPath, text: resource.title }];
+
+  const subs = Object.values(resource.subresources ?? {}).flatMap((sub) =>
+    buildPageNavigation(sub, depth + 1),
+  );
+
+  return [...output, ...subs];
+}
+
+function renderMarkdown(content: string) {
+  return marked.parse(content, { gfm: true }) as string;
+}
+
+async function highlight(content: string, language?: string) {
+  if (language === 'json') return hljs.highlight(content, { language }).value;
+  const highlighter = await astroHighlight();
+  return highlighter.codeToHtml(content, {
+    lang: language ?? 'javascript',
+    themes: HIGHLIGHT_THEMES || {},
+  });
+}
+
+export function SDKSelectReactComponent({
+  selected,
+  languages,
+  id,
+  className,
+}: {
+  selected: DocsLanguage;
+  languages: DocsLanguage[];
+  id: string;
+  className?: string;
+}) {
+  return (
+    <Dropdown id={id} data-current-value={selected} className={className}>
+      <DropdownTrigger
+        className="dropdown-toggle stldocs-button-tertiary"
+        type="button"
+        id="stldocs-snippet-title-button"
+        aria-expanded="false"
+        withChevron
+      >
+        <SDKIcon language={getLanguageSnippet(selected)} size={16} />
+        <span className={clsx('stl-snippet-dropdown-button-text', selected)}>{selected}</span>
+      </DropdownTrigger>
+      <DropdownMenu
+        className="dropdown-menu stl-sdk-select-dropdown-menu"
+        position="below"
+        aria-labelledby="stldocs-snippet-title-button"
+      >
+        {languages.map((item) => (
+          <DropdownItem key={item} value={item} selected={item === selected}>
+            <div>
+              <SDKIcon language={getLanguageSnippet(item)} size={16} />
+              <span className={clsx('stl-snippet-dropdown-button-text', item)}>{item}</span>
+            </div>
+          </DropdownItem>
+        ))}
+      </DropdownMenu>
+    </Dropdown>
+  );
+}
+
+function SDKRequestTitle({ snippetLanguage }: SDKRequestTitleProps) {
+  const spec = useSpec();
+
+  const selected = snippetLanguage.split('.').at(0) as DocsLanguage;
+  const languages = (spec?.docs?.languages ?? ['http']).filter((lang) => !EXCLUDE_LANGUAGES.includes(lang));
+
+  return (
+    <SDKSelectReactComponent
+      selected={selected || 'http'}
+      languages={languages}
+      id="stldocs-snippet-select"
+      className="stl-sdk-select"
+    />
+  );
+}
+
+export type SpecMetadata = [
+  'http' | 'node' | 'python' | 'go' | 'typescript' | 'terraform' | 'ruby' | 'java' | 'kotlin',
+  {
+    repo_url?: string;
+    code_url?: string;
+    package_title?: string;
+    version?: string;
+    install?: string;
+  },
+][];
+
+export function RenderLibraries({ metadata }: { metadata: SpecMetadata }) {
+  return (
+    <ComponentProvider components={{}}>
+      {metadata.map(([language, data]) => (
+        <SDKLanguageBlock
+          language={language}
+          version={data.version || ''}
+          install={data.install || ''}
+          links={{ repo: data.repo_url || '#', docs: `${BASE_PATH}/${language}` }}
+        />
+      ))}
+    </ComponentProvider>
+  );
+}
+
+export function RenderSpecOverview({ spec, language }: { spec: SDKJSON.Spec; language: DocsLanguage }) {
+  const resources = React.useMemo(() => flatResources(spec.resources, []), [spec]);
+
+  return (
+    <DocsProvider spec={spec} language={language ?? 'node'}>
+      <ComponentProvider
+        components={{
+          SDKRequestTitle,
+          SnippetCode,
+          SnippetContainer,
+          SnippetRequestContainer,
+        }}
+      >
+        <NavigationProvider basePath={BASE_PATH}>
+          <MarkdownProvider render={renderMarkdown} highlight={highlight}>
+            <div className={style.Overview}>
+              {resources
+                .filter(({ resource }) => !resource.name.startsWith('$'))
+                .map(({ resource, parents }) => (
+                  <SDKResource
+                    key={resource.stainlessPath}
+                    resource={resource}
+                    parents={parents}
+                    showModels={false}
+                  />
+                ))}
+            </div>
+          </MarkdownProvider>
+        </NavigationProvider>
+      </ComponentProvider>
+    </DocsProvider>
+  );
+}
+
+export function RenderSpec({
+  spec,
+  kind,
+  path,
+  language,
+  currentPath,
+  contentPanelLayout = 'double-pane',
+  transformRequestSnippet,
+}: {
+  spec: SDKJSON.Spec;
+  kind: string;
+  path: string;
+  language: DocsLanguage;
+  currentPath: string;
+  contentPanelLayout?: ContentPanelLayout;
+  transformRequestSnippet?: StlStarlightMiddleware['transformRequestSnippet'];
+}) {
+  const parsed = parseStainlessPath(path);
+  const resource = getResourceFromSpec(path, spec);
+
+  if (!resource || !parsed) return null;
+
+  return (
+    <DocsProvider
+      spec={spec as SDKJSON.Spec}
+      language={language ?? 'node'}
+      settings={{
+        contentPanelLayout,
+        properties: PROPERTY_SETTINGS,
+      }}
+    >
+      <ComponentProvider
+        components={{
+          SDKRequestTitle,
+          SnippetCode,
+          SnippetContainer,
+          SnippetRequestContainer,
+        }}
+      >
+        <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
+          <MarkdownProvider render={renderMarkdown} highlight={highlight}>
+            {kind === 'http_method' ? (
+              <div className="stldocs-root stl-ui-not-prose">
+                <div className="stl-page-nav-container">
+                  <SDKBreadcrumbs
+                    spec={spec as SDKJSON.Spec}
+                    currentPath={currentPath}
+                    basePath={BASE_PATH}
+                    config={BREADCRUMB_CONFIG}
+                  />
+                  <APIReferenceAIDropdown />
+                </div>
+                <SDKMethod
+                  method={resource.methods[parsed.method]}
+                  transformRequestSnippet={transformRequestSnippet}
+                />
+              </div>
+            ) : (
+              <div className="stldocs-root stl-ui-not-prose">
+                <div className="stl-page-nav-container">
+                  <SDKBreadcrumbs
+                    spec={spec as SDKJSON.Spec}
+                    currentPath={currentPath}
+                    basePath={BASE_PATH}
+                    config={BREADCRUMB_CONFIG}
+                  />
+                  <APIReferenceAIDropdown />
+                </div>
+                <SDKOverview resource={resource} />
+              </div>
+            )}
+          </MarkdownProvider>
+        </NavigationProvider>
+      </ComponentProvider>
+    </DocsProvider>
+  );
+}
+
+export function RenderMethod({ path }: { path: string }) {
+  const spec = useSpec();
+  if (!spec) return null;
+
+  const parsed = parseStainlessPath(path);
+  const resource = getResourceFromSpec(path, spec);
+  if (!resource || !parsed) return null;
+
+  const meth = resource.methods[parsed.method];
+  return <SDKMethod method={meth} />;
+}
+
+export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguage) {
+  const repoUrl = spec.metadata?.[language]?.repo_url;
+
+  try {
+    if (repoUrl) {
+      const rawUrl = repoUrl.replace('www.github.com', 'raw.githubusercontent.com');
+
+      const response = await fetch(`${rawUrl}/refs/heads/main/README.md`);
+      if (response && response.ok) return response.text();
+    }
+  } catch {
+    // ignore
+  }
+
+  return spec.readme[language];
+}
+
+// Astro's markdown processor is a singleton
+// Need to cache it instead of instanting per request
+let astroMarkdownProcessor: MarkdownProcessor;
+async function astroMarkdown() {
+  if (!astroMarkdownProcessor) {
+    astroMarkdownProcessor = await createMarkdownProcessor({
+      gfm: true,
+      remarkPlugins: [remarkGfmAlerts],
+      shikiConfig: {
+        themes: HIGHLIGHT_THEMES,
+      },
+    });
+  }
+
+  return astroMarkdownProcessor;
+}
+
+let astroShikiHighlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
+async function astroHighlight() {
+  if (!astroShikiHighlighter) {
+    astroShikiHighlighter = await createHighlighter({
+      themes: ['github-light', 'github-dark'],
+      langs: SupportedLanguageSyntaxes,
+    });
+  }
+
+  return astroShikiHighlighter;
+}
+
+export async function astroMarkdownRender(content: string) {
+  const md = await astroMarkdown();
+  const output = await md.render(content);
+
+  // Map GFM callouts to the closest Starlight equivalent
+  output.code = output.code
+    .replaceAll('markdown-alert-caution', 'markdown-alert-danger')
+    .replaceAll('markdown-alert-warning', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-important', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-title', 'starlight-aside__title')
+    .replaceAll('markdown-alert-', 'starlight-aside--')
+    .replaceAll('markdown-alert', 'starlight-aside');
+
+  return output;
+}

package/plugin/referencePlaceholderUtils.ts

@@ -0,0 +1,82 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import type starlight from '@astrojs/starlight';
+
+// file is required because of build errors when importing from index.ts in the replaceSidebarPlaceholderMiddleware.ts file
+const INTERNAL_REFERENCE_ENTRY_MARKER = 'STL_STARLIGHT_API_REFERENCE_ITEMS_PLACEHOLDER';
+
+export function makePlaceholderItems(id: number) {
+  return [
+    {
+      label: 'API Reference',
+      link: '/', // this gets replaced during plugin initialization
+      attrs: {
+        // we hack-ily use/abuse the about attribute to identify the placeholder item
+        // using "about" was sort of a random choice, but it seems good enough
+        about: INTERNAL_REFERENCE_ENTRY_MARKER,
+        'data-stldocs-sidebar-id': id,
+      },
+    },
+  ];
+}
+
+type StarlightConfig = Parameters<typeof starlight>[0];
+
+type SidebarConfigEntry = Exclude<StarlightConfig['sidebar'], undefined>[number];
+
+export function getAPIReferencePlaceholderItemFromSidebarConfig(
+  sidebar: SidebarConfigEntry[],
+): SidebarConfigEntry | null {
+  for (const item of sidebar) {
+    if (typeof item === 'string') {
+      continue;
+    }
+    if ('items' in item) {
+      const found = getAPIReferencePlaceholderItemFromSidebarConfig(item.items);
+      if (found) {
+        return found;
+      }
+    }
+    if ('attrs' in item && item.attrs?.about === INTERNAL_REFERENCE_ENTRY_MARKER) {
+      return item;
+    }
+  }
+
+  return null;
+}
+
+type SidebarEntry = StarlightRouteData['sidebar'][number];
+
+type PlaceholderItemResult = {
+  index: number;
+  group: SidebarEntry[];
+  placeholder: SidebarEntry;
+  sidebarId: number;
+};
+
+function recursiveGetPlaceholderItems(
+  sidebar: SidebarEntry[],
+  items: PlaceholderItemResult[],
+): PlaceholderItemResult[] {
+  for (let i = 0; i < sidebar.length; i++) {
+    const entry = sidebar[i];
+    if ('attrs' in entry && entry.attrs?.about === INTERNAL_REFERENCE_ENTRY_MARKER) {
+      items.push({
+        index: i,
+        group: sidebar,
+        placeholder: entry,
+        sidebarId: entry.attrs?.['data-stldocs-sidebar-id'],
+      });
+    }
+    if (entry.type === 'group') {
+      const foundEntries = getAPIReferencePlaceholderItems(entry.entries);
+      if (foundEntries) {
+        items.push(...foundEntries);
+      }
+    }
+  }
+  return items;
+}
+
+export function getAPIReferencePlaceholderItems(sidebar: SidebarEntry[]): PlaceholderItemResult[] {
+  return recursiveGetPlaceholderItems(sidebar, []);
+}

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -0,0 +1,50 @@
+import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
+
+import { cmsClient } from './cms/client';
+import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+import { getAPIReferencePlaceholderItems } from './referencePlaceholderUtils';
+import { getMethodFromSDKJSON, recursiveReplacePlaceholderItems } from './generateAPIReferenceLink';
+import { forceGenerateRoute } from './cms/sidebar-builder';
+import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+
+// 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 apiReferencePlaceholderItems = getAPIReferencePlaceholderItems(context.locals.starlightRoute.sidebar);
+
+  const spec = await cmsClient.getSpec();
+
+  const { language, stainlessPath } = parseRoute(BASE_PATH, slug);
+
+  // This is probably temporary, but it fills in functionality needed for Mintlify imports
+  recursiveReplacePlaceholderItems(context.locals.starlightRoute.sidebar, (entry, { endpoint, label }) => {
+    const method = getMethodFromSDKJSON(spec, endpoint);
+
+    const route = forceGenerateRoute({
+      basePath: BASE_PATH,
+      stainlessPath: method.stainlessPath,
+      language,
+    });
+    entry.href = route;
+    entry.isCurrent = method.stainlessPath === stainlessPath;
+    if (!label) {
+      entry.label = method.summary ?? method.name;
+    }
+    entry.attrs['data-stldocs-method'] = method.httpMethod;
+  });
+
+  for (const item of apiReferencePlaceholderItems) {
+    const entries = await cmsClient.buildSidebar({
+      basePath: BASE_PATH,
+      currentSlug: slug,
+      sidebarId: item.sidebarId,
+    });
+
+    item.group.splice(item.index, 1, ...entries);
+  }
+});