@stainless-api/docs 0.1.0-beta.0

package/plugin/cms/sidebar-builder.ts

@@ -0,0 +1,420 @@
+import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+
+function isResourceNonEmpty(resource: SDKJSON.Resource) {
+  return (
+    Object.keys(resource.methods ?? {}).length > 0 ||
+    Object.keys(resource.subresources ?? {}).length > 0 ||
+    Object.keys(resource.models ?? {}).length > 0
+  );
+}
+
+interface UserSidebarConfigItem {
+  label: string;
+  badge: StarlightRouteData['sidebar'][number]['badge'];
+}
+
+type MethodMetadata = {
+  deprecated: boolean;
+  methodName: string;
+  title: string;
+  summary: string | undefined;
+  description: string | undefined;
+  httpMethod: string;
+};
+interface UserSidebarMethodPage extends UserSidebarConfigItem {
+  /**
+   * The kind is the type of the item that will be generated.
+   */
+  kind: 'method_page';
+  /**
+   * The key + kind is how Stainless identifies the item to build the final sidebar.
+   * DO NOT modify the key or kind of the item.
+   * You may change any other properties like the label. You may also completely remove the item.
+   *
+   * Example: post v1/{accounts}/charges
+   * The key is identical to the endpoint specified in your Stainless config file.
+   */
+  key: string;
+  metadata: MethodMetadata;
+}
+
+interface UserSidebarResourceOverviewPage extends UserSidebarConfigItem {
+  /**
+   * The kind is the type of the item that will be generated.
+   */
+  kind: 'resource_overview_page';
+  /**
+   * The key + kind is how Stainless identifies the item to build the final sidebar.
+   * DO NOT modify the key or kind of the item.
+   * You may change any other properties like the label. You may also completely remove the item.
+   *
+   * Example: #/resources/accounts/subresources/charges
+   * The key is the path to the resource specified in your Stainless config file.
+   */
+  key: string;
+  metadata: {
+    subResourceCount: number;
+    methodCount: number;
+    modelCount: number;
+  };
+}
+
+interface UserSidebarAPIOverviewPage extends UserSidebarConfigItem {
+  /**
+   * The kind is the type of the item that will be generated.
+   */
+  kind: 'api_overview_page';
+  /**
+   * The key + kind is how Stainless identifies the item to build the final sidebar.
+   * DO NOT modify the key or kind of the item.
+   * You may change any other properties like the label. You may also completely remove the item.
+   *
+   * Example: #/resources/accounts/subresources/charges
+   * The key is the path to the resource specified in your Stainless config file.
+   */
+  key: 'api_overview_page';
+}
+
+interface ReferenceSidebarGroup extends UserSidebarConfigItem {
+  kind: 'group';
+  label: string;
+  /**
+   * Whether the group should be collapsed by default.
+   */
+  collapsed: boolean;
+  /**
+   * If this group is a group for a resource, this will be the key of the resource.
+   */
+  resourceGroupKey?: string;
+  entries: ReferenceSidebarConfigItem[];
+}
+
+export type ReferenceSidebarConfigItem =
+  | UserSidebarMethodPage
+  | UserSidebarResourceOverviewPage
+  | UserSidebarAPIOverviewPage
+  | ReferenceSidebarGroup;
+
+export type ReferenceSidebarConfigGenerateOptions = {
+  /**
+   * Whether to include a "shared" page for models defined at the client level in the sidebar.
+   * Defaults to `false`.
+   */
+  includeSharedModels?: boolean;
+
+  /**
+   * Whether to exclude the resource overview page for each resource in the sidebar.
+   * Defaults to `false`.
+   */
+  excludeResourceOverviewPages?: boolean;
+};
+
+export type GeneratedSidebarConfig = {
+  options?: ReferenceSidebarConfigGenerateOptions | undefined;
+  transformFn?: (
+    sidebar: ReferenceSidebarConfigItem[],
+    language: DocsLanguage,
+  ) => ReferenceSidebarConfigItem[] | void;
+};
+
+function countKeys(obj?: Record<string, any>) {
+  let o = obj ?? {};
+  return Object.keys(o).length;
+}
+
+function getMethodDeclForLanguage(entry: SDKJSON.Method, spec: SDKJSON.Spec, language: DocsLanguage) {
+  const decls = spec.decls[language] ?? {};
+  const decl = decls[entry.stainlessPath];
+  if (decl !== undefined) {
+    if ('ident' in decl) {
+      return decl;
+    }
+  }
+  return null;
+}
+
+type MethodDecl = Exclude<ReturnType<typeof getMethodDeclForLanguage>, null>;
+
+function makeAPIOverviewPage(): UserSidebarAPIOverviewPage {
+  return {
+    kind: 'api_overview_page',
+    label: 'Overview',
+    key: 'api_overview_page',
+    badge: undefined,
+  };
+}
+
+function pullOutSharedModelsResource(resources: SDKJSON.Resource[]): {
+  resources: SDKJSON.Resource[];
+  sharedModelsResource: SDKJSON.Resource | null;
+} {
+  let sharedModelsResource: SDKJSON.Resource | null = null;
+  const remainingResources = resources.filter((r) => {
+    if (r.configRef === '#/resources/$shared') {
+      sharedModelsResource = r;
+      return false;
+    }
+    return true;
+  });
+
+  return {
+    resources: remainingResources,
+    sharedModelsResource,
+  };
+}
+
+export class SidebarConfigItemsBuilder {
+  private getMethodDeclForLanguage(entry: SDKJSON.Method) {
+    const decls = this.spec.decls[this.language] ?? {};
+    const decl = decls[entry.stainlessPath];
+    if (decl !== undefined) {
+      if ('ident' in decl) {
+        return decl;
+      }
+    }
+    return null;
+  }
+
+  private toResourceOverviewPage(entry: SDKJSON.Resource): UserSidebarResourceOverviewPage {
+    return {
+      kind: 'resource_overview_page',
+      label: 'Overview',
+      key: entry.configRef,
+      badge: undefined,
+      metadata: {
+        subResourceCount: countKeys(entry.subresources),
+        methodCount: countKeys(entry.methods),
+        modelCount: countKeys(entry.models),
+      },
+    };
+  }
+
+  private toMethodPage(entry: SDKJSON.Method, decl: MethodDecl): UserSidebarMethodPage {
+    return {
+      kind: 'method_page',
+      label: entry.title,
+      key: entry.endpoint,
+      badge: undefined,
+      metadata: {
+        deprecated: Boolean(entry.deprecated),
+        methodName: this.language === 'http' ? entry.name : decl.ident,
+        title: entry.title,
+        summary: entry.summary,
+        description: entry.description,
+        httpMethod: entry.httpMethod,
+      },
+    };
+  }
+
+  private sortByLabel<T extends UserSidebarConfigItem>(items: T[]) {
+    // sorts in place
+    items.sort((a, b) => {
+      return a.label.localeCompare(b.label);
+    });
+  }
+
+  private generateResourceGroup(resource: SDKJSON.Resource, collapsed: boolean): ReferenceSidebarGroup {
+    const entries: ReferenceSidebarConfigItem[] = [];
+    if (!this.options?.excludeResourceOverviewPages) {
+      entries.push(this.toResourceOverviewPage(resource));
+    }
+    const methods = Object.values(resource.methods ?? {});
+    const methodPages: UserSidebarMethodPage[] = [];
+    for (const m of methods) {
+      const langDecl = this.getMethodDeclForLanguage(m);
+      if (langDecl) {
+        methodPages.push(this.toMethodPage(m, langDecl));
+      }
+    }
+    this.sortByLabel(methodPages);
+    entries.push(...methodPages);
+
+    const subresources = Object.values(resource.subresources ?? {});
+    const subresourceGroups: ReferenceSidebarGroup[] = [];
+    for (const sub of subresources) {
+      if (isResourceNonEmpty(sub)) {
+        subresourceGroups.push(this.generateResourceGroup(sub, true));
+      }
+    }
+    this.sortByLabel(subresourceGroups);
+    entries.push(...subresourceGroups);
+
+    return {
+      kind: 'group',
+      badge: undefined,
+      label: resource.title,
+      resourceGroupKey: resource.configRef,
+      entries,
+      collapsed,
+    };
+  }
+
+  public generateItems(): ReferenceSidebarConfigItem[] {
+    const resourceMap = this.spec.resources;
+    let { resources, sharedModelsResource } = pullOutSharedModelsResource(Object.values(resourceMap ?? {}));
+
+    const entries: ReferenceSidebarConfigItem[] = resources.filter(isResourceNonEmpty).map((r) => {
+      return this.generateResourceGroup(r, false);
+    });
+
+    const includeSharedModels = this.options?.includeSharedModels ?? false;
+    if (includeSharedModels && sharedModelsResource) {
+      entries.unshift(this.toResourceOverviewPage(sharedModelsResource));
+    }
+
+    entries.unshift(makeAPIOverviewPage());
+
+    return entries;
+  }
+
+  constructor(
+    private spec: SDKJSON.Spec,
+    private language: DocsLanguage,
+    private options?: ReferenceSidebarConfigGenerateOptions,
+  ) {}
+}
+
+export function walkSidebarConfigItems(
+  sidebar: ReferenceSidebarConfigItem[],
+  fn: (item: ReferenceSidebarConfigItem) => void,
+) {
+  for (const item of sidebar) {
+    fn(item);
+    if (item.kind === 'group') {
+      walkSidebarConfigItems(item.entries, fn);
+    }
+  }
+}
+
+type SidebarEntry = StarlightRouteData['sidebar'][number];
+
+// This allows us to be a bit more forgiving to the user.
+// As long as they don't modify the key, we can still find the item.
+function getResourceOrMethod(spec: SDKJSON.Spec, endpointOrConfigRef: string) {
+  for (const entry of walkTree(spec, false)) {
+    if (entry.data.kind === 'resource' && entry.data.configRef === endpointOrConfigRef) {
+      return entry;
+    }
+    if (entry.data.kind === 'http_method' && entry.data.endpoint === endpointOrConfigRef) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+export function forceGenerateRoute({
+  basePath,
+  stainlessPath,
+  language,
+}: {
+  basePath: string;
+  stainlessPath: string;
+  language: DocsLanguage;
+}) {
+  const route = generateRoute(basePath, language, stainlessPath);
+  if (!route) {
+    throw new Error(`Route for path ${stainlessPath} failed to generate`);
+  }
+  return route;
+}
+
+export type BuildSidebarParams = {
+  basePath: string;
+  currentSlug: string;
+};
+
+type ToStarlightSidebarParams = BuildSidebarParams & {
+  spec: SDKJSON.Spec;
+  entries: ReferenceSidebarConfigItem[];
+  currentStainlessPath: string;
+  currentLanguage: DocsLanguage;
+};
+
+export function toStarlightSidebar({
+  basePath,
+  currentSlug,
+  spec,
+  entries,
+  currentStainlessPath,
+  currentLanguage,
+}: ToStarlightSidebarParams): SidebarEntry[] {
+  const starlightEntries: SidebarEntry[] = [];
+
+  for (const entry of entries) {
+    if (entry.kind === 'api_overview_page') {
+      const readmeSlug = currentLanguage === 'http' ? basePath : `${basePath}/${currentLanguage}`;
+
+      starlightEntries.push({
+        type: 'link',
+        href: readmeSlug,
+        label: entry.label,
+        isCurrent: currentSlug === readmeSlug,
+        badge: entry.badge,
+        attrs: {
+          'data-stldocs-overview': 'readme',
+        },
+      });
+    } else if (entry.kind === 'resource_overview_page' || entry.kind === 'method_page') {
+      const resourceOrMethod = getResourceOrMethod(spec, entry.key);
+      if (!resourceOrMethod) {
+        throw new Error(
+          `Resource or method not found for key ${entry.key} Make sure you don't modify the key.`,
+        );
+      }
+      const route = forceGenerateRoute({
+        basePath,
+        stainlessPath: resourceOrMethod.data.stainlessPath,
+        language: currentLanguage,
+      });
+
+      const isCurrent = resourceOrMethod.data.stainlessPath === currentStainlessPath;
+
+      if (resourceOrMethod.data.kind === 'http_method') {
+        starlightEntries.push({
+          type: 'link',
+          href: route,
+          label: entry.label,
+          isCurrent,
+          badge: entry.badge,
+          attrs: {
+            'data-stldocs-method': resourceOrMethod.data.httpMethod,
+          },
+        });
+      } else if (resourceOrMethod.data.kind === 'resource') {
+        starlightEntries.push({
+          type: 'link',
+          href: route,
+          label: entry.label,
+          isCurrent,
+          badge: entry.badge,
+          attrs: {
+            // TODO: @Ryan: is data.name unique? This is what we used before so I'm not changing, but I am curious.
+            'data-stldocs-overview': resourceOrMethod.data.name,
+          },
+        });
+      } else {
+        throw new Error(`Unknown entry kind ${JSON.stringify(entry)}`);
+      }
+    } else if (entry.kind === 'group') {
+      starlightEntries.push({
+        type: 'group',
+        label: entry.label,
+        entries: toStarlightSidebar({
+          basePath,
+          currentSlug,
+          spec,
+          currentStainlessPath,
+          entries: entry.entries,
+          currentLanguage,
+        }),
+        collapsed: entry.collapsed,
+        badge: entry.badge,
+      });
+    } else {
+      throw new Error(`Unknown entry kind ${JSON.stringify(entry)}`);
+    }
+  }
+  return starlightEntries;
+}

package/plugin/cms/worker.ts

@@ -0,0 +1,122 @@
+import Worker from 'web-worker';
+import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import fs from 'fs/promises';
+import pathutils from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const workerPath = resolve(__dirname, '..', 'vendor', 'preview.worker.docs.js');
+
+type OpenAPIDocument = Record<string, any>;
+type ParsedConfig = Record<string, any>;
+
+function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; data: any }) {
+  const stainlessWorker = new Worker(workerPath, {
+    type: 'module',
+    name: 'Preview server',
+  });
+
+  return new Promise<any>((resolve, reject) => {
+    stainlessWorker.addEventListener('error', (e) => {
+      reject(e);
+    });
+
+    stainlessWorker.addEventListener('messageerror', (e) => {
+      reject(e);
+    });
+
+    stainlessWorker.addEventListener('message', (message) => {
+      if (message.data.type === `${type}_done`) {
+        resolve(message.data);
+      } else if (message.data.type === `${type}_failed`) {
+        const { name, message: errorMessage } = message.data;
+        const err = new Error(errorMessage);
+        err.name = name;
+        reject(err);
+      }
+    });
+
+    if (signal) {
+      signal.onabort = () => reject({ type: 'abort' });
+    }
+
+    if (signal?.aborted) {
+      reject({ type: 'abort' });
+    }
+
+    stainlessWorker.postMessage({ ...data, type });
+  }).finally(() => {
+    stainlessWorker.terminate();
+  });
+}
+
+export async function parseInputs({ oas, config }: { oas: string; config: string }) {
+  const result = await runJob({
+    type: 'parse',
+    data: {
+      oas,
+      config,
+    },
+  });
+
+  return result as {
+    oas: OpenAPIDocument;
+    config: ParsedConfig;
+  };
+}
+
+export async function transformOAS({ oas, config }: { oas: OpenAPIDocument; config: ParsedConfig }) {
+  const result = await runJob({
+    type: 'transform',
+    data: {
+      oas,
+      config,
+    },
+  });
+
+  return result.transformedOAS;
+}
+
+export async function createSDKJSON({
+  oas,
+  config,
+  languages,
+}: {
+  oas: OpenAPIDocument;
+  config: ParsedConfig;
+  languages: DocsLanguage[];
+}) {
+  const templatePath = resolve(__dirname, '../vendor/templates');
+  const readmeLoader = await Promise.all(
+    Languages.map(async (language) => {
+      const mdfile = pathutils.join(templatePath, `${language}.md`);
+
+      try {
+        const content = await fs.readFile(mdfile);
+        return [language, content.toString()];
+      } catch (err) {
+        return [language, null];
+      }
+    }),
+  );
+
+  const readmeTemplates = Object.fromEntries(readmeLoader);
+
+  const result = await runJob({
+    type: 'preview',
+    data: {
+      oas,
+      config,
+      languages,
+      transform: false,
+      projectName: '',
+      readmeTemplates,
+    },
+  });
+
+  return result.spec as SDKJSON.Spec;
+}

package/plugin/components/SDKSelect.astro

@@ -0,0 +1,154 @@
+---
+import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import { cmsClient } from '../cms/client';
+import { BASE_PATH, DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { Languages } from '../languages';
+import { SDKSelectReactComponent } from '../react/Routing';
+
+const slug = `/${Astro.locals.starlightRoute.id}`;
+
+const basePath = BASE_PATH;
+const defaultLanguage = DEFAULT_LANGUAGE;
+const { language, stainlessPath } = parseRoute(basePath, slug);
+
+const data = {
+  language,
+  basePath,
+  stainlessPath,
+  defaultLanguage,
+};
+
+const spec = await cmsClient.getSpec();
+
+// TODO: should not force unwrap this
+const languages: DocsLanguage[] = spec.docs!.languages ?? ['http'];
+const options = languages
+  .filter((language) => language !== 'terraform')
+  .filter((language) => !EXCLUDE_LANGUAGES.includes(language))
+  .map((value) => ({
+    value,
+    label: Languages[value].name,
+    selected: data.language === value,
+  }));
+
+const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
+---
+
+<span
+  hidden
+  id="stldocs-data"
+  data-stldocs-basepath={data.basePath}
+  data-stldocs-defaultLanguage={data.defaultLanguage}></span>
+
+{
+  (data.stainlessPath || slug === readmeSlug) && (
+    <div class="stldocs-root stl-sdk-select">
+      <SDKSelectReactComponent
+        selected={data.language}
+        languages={options.map(({ value }) => value)}
+        id="sidebar-sdk-select"
+      />
+    </div>
+  )
+}
+
+<style>
+  @layer starlight.core {
+    label {
+      --sl-label-icon-size: 16px;
+      --sl-caret-size: 1.25rem;
+      --sl-inline-padding: 0.5rem;
+      position: relative;
+      display: flex;
+      align-items: center;
+      gap: 0.25rem;
+      color: var(--sl-color-gray-1);
+    }
+
+    label:hover {
+      color: var(--sl-color-gray-2);
+    }
+
+    .icon {
+      position: absolute;
+      top: 50%;
+      transform: translateY(-50%);
+      pointer-events: none;
+      width: 16px;
+    }
+
+    select {
+      padding-block: 0.3rem;
+      padding-inline: calc(var(--sl-label-icon-size) + var(--sl-inline-padding) + 0.5rem)
+        calc(var(--sl-caret-size) + var(--sl-inline-padding) + 0.25rem);
+      margin-inline: calc(var(--sl-inline-padding) * -1);
+      width: calc(var(--sl-select-width) + var(--sl-inline-padding) * 2);
+      text-overflow: ellipsis;
+      color: inherit;
+      cursor: pointer;
+      appearance: none;
+      font-weight: 600;
+      text-transform: capitalize;
+    }
+
+    select:active {
+      font-weight: inherit;
+      /* font-family: sans-serif;
+      font-weight: 400; */
+    }
+
+    option {
+      background-color: var(--sl-color-bg-nav);
+      color: var(--sl-color-gray-1);
+    }
+
+    @media (min-width: 50rem) {
+      select {
+        font-size: var(--sl-text-sm);
+      }
+    }
+  }
+
+  @layer starlight.components {
+    .label-icon {
+      font-size: var(--sl-label-icon-size);
+      inset-inline-start: 0;
+    }
+
+    .caret {
+      font-size: var(--sl-caret-size);
+      inset-inline-end: 0;
+    }
+  }
+
+  .custom-select-wrapper {
+    --sl-inline-padding: 0.5rem;
+    position: relative;
+    display: inline-block;
+    /* These match the padding on the sidebar menu */
+    padding-left: var(--sl-inline-padding);
+    padding-right: var(--sl-inline-padding);
+
+    .icon.http path {
+      fill: var(--sl-color-text);
+    }
+  }
+</style>
+<script>
+  import { navigate } from 'astro:transitions/client';
+  import { updateSelectedLanguage } from '../languages';
+  import { initDropdown } from '@stainless-api/docs-ui/src/components/scripts/dropdown';
+  import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+  import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
+
+  document.addEventListener(getPageLoadEvent(), () => {
+    initDropdown({
+      dropdownId: 'sidebar-sdk-select',
+      onSelect: (value) => {
+        const originalLanguage = document.getElementById('sidebar-sdk-select')?.dataset.currentValue;
+        navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
+      },
+    });
+  });
+</script>