@stainless-api/docs 0.1.0-beta.13 → 0.1.0-beta.131

package/plugin/routes/Docs.astro

@@ -1,79 +1,79 @@
 ---
-import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
-import { cmsClient } from "../cms/client";
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { getReadmeContent, buildPageNavigation, RenderSpec } from '../react/Routing';
+import { astroMarkdownRender } from '../markdown';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
+import { parseRoute, parseStainlessPath } from '@stainless-api/docs-ui/routing';
 import {
-  getReadmeContent,
-  generateDocsRoutes,
-  buildPageNavigation,
-  RenderSpec,
-  astroMarkdownRender,
-} from "../react/Routing";
-import { getResourceFromSpec } from "@stainless-api/docs-ui/src/utils";
-import { BASE_PATH, CONTENT_PANEL_LAYOUT,MIDDLEWARE } from "virtual:stl-starlight-virtual-module";
+  CONTENT_PANEL_LAYOUT,
+  MIDDLEWARE,
+  EXPERIMENTAL_REQUEST_BUILDER,
+  RESOLVED_API_REFERENCE_PATH,
+} from 'virtual:stl-starlight-virtual-module';
+import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
+import { StainlessIslands } from '../components/StainlessIslands';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
 
+const language = parseRoute(RESOLVED_API_REFERENCE_PATH, Astro.url.pathname)?.language;
 
-const spec = await cmsClient.getSpec();
-const routes = generateDocsRoutes(spec);
+const spec = await getSDKJSONInSSR(language);
 
-const route = routes.find((r) => r.params.slug === Astro.params.slug);
+export type Props = Awaited<ReturnType<typeof generateDocsRoutes>>[number]['props'] | Record<string, never>;
 
-if (!route) {
-  throw new Error("No such route");
-}
+const props =
+  'language' in Astro.props
+    ? // In prod, we pass the props down to this page
+      Astro.props
+    : // In the dev server, we skip the DocsStatic wrapper so we need to find the props ourselves
+      generateDocsRoutes(spec).find((r) => r.params.slug === Astro.params.slug)?.props;
+if (!props) throw new Error(`Could not find a route for slug '${Astro.params.slug}'`);
+
+// PageTitle override will skip rendering the default Starlight title
+Astro.locals._stlStarlightPage = {
+  skipRenderingStarlightTitle: props.kind === 'readme' ? false : true,
+};
 
-const readmeContent = await getReadmeContent(spec, route.props.language);
-const readme =
-  route.props.kind === "readme"
-    ? await astroMarkdownRender(readmeContent ?? "")
-    : null;
+const readmeContent = await getReadmeContent(spec, props.language);
+const readme = props.kind === 'readme' ? await astroMarkdownRender(readmeContent ?? '') : null;
 
-const resource = route.props.stainlessPath
-  ? getResourceFromSpec(route.props.stainlessPath, spec)
-  : null;
+const resource = props.stainlessPath ? getResourceFromSpec(props.stainlessPath, spec) : null;
 
 const pageNav =
-  route.props.kind === "resource" && resource
+  props.kind === 'resource' && resource
     ? buildPageNavigation(resource)
-    : route.props.kind === "readme" && readme?.metadata
+    : props.kind === 'readme' && readme?.metadata
       ? readme?.metadata.headings
       : [];
 
-const props = route.props;
+Astro.locals.language = props.language;
 
+// Use first heading in README as page title
 if (readme) {
   const repo = spec.metadata?.[props.language]?.code_url;
-  readme.code = readme.code.replace(
-    /<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g,
-    `<a href="${repo}/$1"`);
-  props.title = readme.metadata.headings[0].text ?? "Overview";
+  readme.code = readme.code.replace(/<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g, `<a href="${repo}/$1"`);
+  props.title = readme.metadata.headings[0]!.text ?? 'Overview';
 }
 
+// use summary for the page title of method pages
+if (props.kind === 'http_method' && props.stainlessPath) {
+  const parsed = parseStainlessPath(props.stainlessPath);
+  const resource = getResourceFromSpec(props.stainlessPath, spec);
+  if (parsed?.method && resource?.methods[parsed.method]) {
+    const method = resource.methods[parsed.method];
+    props.title = method?.summary ?? method?.title ?? props.title;
+  }
+}
 ---
 
-
 <StarlightPage
   headings={pageNav}
   frontmatter={{
-    title: props?.title,
-    head: [
-      {
-        tag: "link",
-        attrs: {
-          rel: "alternate",
-          type: "text/markdown",
-          href: `${BASE_PATH}/${Astro.params.slug}.md`
-        }
-      }
-    ],
+    title: props.title,
     pagefind: false,
-    tableOfContents: ["resource", "readme"].includes(props.kind)
-      ? { maxHeadingLevel: 6 }
-      : false,
-    // @ts-ignore
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      ...props,
-    },
+    tableOfContents:
+      props.kind === 'readme' || (props.kind === 'resource' && props.language !== 'terraform')
+        ? { maxHeadingLevel: 6 }
+        : false,
   }}
 >
   {
@@ -88,76 +88,37 @@ if (readme) {
           contentPanelLayout={CONTENT_PANEL_LAYOUT}
           transformRequestSnippet={MIDDLEWARE.transformRequestSnippet}
         />
-
-        <style is:inline>
-          #stldocs-snippet-title {
-            display: flex;
-            gap: 5px;
-          }
-
-          .stldocs-snippet-code:not(.stldocs-snippet-response .stldocs-snippet-code) {
-            padding: 0 !important;
-            
-            .astro-code {
-              padding: 1rem;
-            }
-          }
-
-
-          [data-has-sidebar]:not([data-has-toc]) .sl-container {
-            max-width: 1428px;
-          }
-
-          .content-panel:nth-of-type(1) {
-            display: none;
-          }
-          .content-panel:nth-of-type(2) .stl-page-nav-container {
-            display: none;
-          }
-
-          .content-panel:nth-of-type(2) .stldocs-root .stl-page-nav-container {
-            display: flex;
-          }
-        </style>
       </div>
     ) : (
       <>
         <Fragment set:html={readme?.code} />
-        <style is:inline>
-          .sl-markdown-content h1:first-of-type {
-            display: none;
-          }
-
-          .sl-markdown-content img {
-            display: inline-block;
-            vertical-align: text-bottom;
-          }
-
-          .sl-markdown-content .octicon {
-            margin-right: 0.2rem;
-            overflow: visible !important;
-            -webkit-mask: var(--oct-icon) no-repeat;
-            mask: var(--oct-icon) no-repeat;
-            -webkit-mask-size: 100% 100%;
-            mask-size: 100% 100%;
-            background-color: currentColor;
-            color: inherit;
-            display: inline-block;
-            vertical-align: text-bottom;
-            width: 1em;
-            height: 1em;
-          }
-
-          .sl-markdown-content code {
-            white-space: pre-wrap;
-          }
-        </style>
+        <style
+          is:inline
+          set:text={`
+            .sl-markdown-content h1:first-of-type {
+              display: none;
+            }
+
+            .sl-markdown-content img {
+              display: inline-block;
+              vertical-align: text-bottom;
+            }
+
+            .sl-markdown-content code {
+              white-space: pre-wrap;
+            }
+          `}
+        />
       </>
     )
   }
 </StarlightPage>
 
+{EXPERIMENTAL_REQUEST_BUILDER && <StainlessIslands client:load />}
+
 <script src="../globalJs/navigation.ts"></script>
 <script src="../globalJs/copy.ts"></script>
 <script src="../globalJs/tooltip.ts"></script>
 <script src="../globalJs/code-snippets.ts"></script>
+<script src="../globalJs/method-descriptions.ts"></script>
+<script src="../globalJs/summary-selection-tweak.ts"></script>

package/plugin/routes/DocsStatic.astro

@@ -1,14 +1,15 @@
 ---
 import type { GetStaticPaths } from 'astro';
 import Docs from './Docs.astro';
-import { cmsClient } from '../cms/client';
-import { generateDocsRoutes } from '../react/Routing';
+import { generateAllDocsRoutes } from '../helpers/generateDocsRoutes';
 
 export const getStaticPaths = (async () => {
-  const spec = await cmsClient.getSpec();
-  const routes = generateDocsRoutes(spec);
+  const routes = await generateAllDocsRoutes();
   return routes;
 }) satisfies GetStaticPaths;
+
+export type Props = Awaited<ReturnType<typeof getStaticPaths>>[number]['props'];
+const props = Astro.props;
 ---
 
-<Docs />
+<Docs {...props} />

package/plugin/routes/Overview.astro

@@ -1,17 +1,36 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import { BASE_PATH, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
-import { cmsClient } from '../cms/client';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { RenderLibraries, RenderSpecOverview, type SpecMetadata } from '../react/Routing';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
+import { api } from 'virtual:stainless-apis-manifest';
 
-const spec = await cmsClient.getSpec();
+const spec = await getSDKJSONInSSR('http');
 
-const languages: DocsLanguage[] = spec.docs!.languages ?? ['http'];
-const metadata = languages
-  .filter((language) => !['http', 'terraform'].includes(language) && spec.metadata[language])
-  .filter((language) => !EXCLUDE_LANGUAGES.includes(language))
-  .map((language) => [language, spec.metadata[language]]) as SpecMetadata;
+const langTargets = api.languages
+  .map((l) => l.language)
+  .filter((l) => !EXCLUDE_LANGUAGES.includes(l))
+  .filter((l) => l !== 'http');
+
+const langsWithSpecs = await Promise.all(
+  langTargets.map(async (language) => {
+    const spec = await getSDKJSONInSSR(language);
+    return {
+      language,
+      spec,
+    };
+  }),
+);
+
+const metadata: SpecMetadata = langsWithSpecs.map(({ language, spec }) => [
+  language,
+  spec.metadata[language]!,
+]);
+
+// PageTitle override will skip rendering the default Starlight title
+Astro.locals._stlStarlightPage = {
+  hasMarkdownRoute: false,
+};
 ---
 
 <StarlightPage
@@ -19,22 +38,26 @@ const metadata = languages
     title: 'API Reference',
     pagefind: false,
     tableOfContents: false,
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      language: 'http',
-    },
   }}
 >
-  <h3>Libraries</h3>
+  <div class="stl-overview">
+    {
+      metadata.length > 0 && (
+        <>
+          <h3>Libraries</h3>
 
-  <div class="stldocs-root language-blocks stl-ui-not-prose not-content">
-    <RenderLibraries metadata={metadata} />
-  </div>
+          <div class="stldocs-root language-blocks stl-ui-not-prose not-content">
+            <RenderLibraries metadata={metadata} />
+          </div>
+        </>
+      )
+    }
 
-  <h3>API Overview</h3>
+    <h3>API Overview</h3>
 
-  <div class="stldocs-root api-overview stl-ui-not-prose">
-    <RenderSpecOverview spec={spec} language="http" />
+    <div class="stldocs-root api-overview stl-ui-not-prose">
+      <RenderSpecOverview spec={spec} language="http" />
+    </div>
   </div>
 </StarlightPage>
 
@@ -45,8 +68,9 @@ const metadata = languages
     gap: 1rem;
     margin-top: 2rem;
 
-    .stldocs-language-block {
-      width: 350px;
+    > * {
+      width: 0;
+      flex: 1 1 350px;
     }
   }
 

package/plugin/routes/llms.ts

@@ -0,0 +1,186 @@
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { base as ASTRO_BASE } from 'astro:config/server';
+import { SITE_TITLE, API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
+import { LLMS_TXT_DESCRIPTION, LLMS_TXT_DETAIL_THRESHOLD } from 'virtual:stl-starlight-virtual-module';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
+import Markdoc from '@markdoc/markdoc';
+import type { Node } from '@markdoc/markdoc';
+import * as md from '@stainless-api/docs-ui/markdown/md';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { generateRoute, walkTree } from '@stainless-api/docs-ui/routing';
+
+export const prerender = true;
+
+function joinUrlParts(...parts: (string | boolean | null | undefined)[]) {
+  return (
+    '/' +
+    parts
+      .map((p) => {
+        if (typeof p === 'string') {
+          return p.split('/');
+        }
+        return p;
+      })
+      .flat()
+      .filter(Boolean)
+      .join('/')
+  );
+}
+
+export type ProsePageEntry = {
+  id: string;
+  title: string;
+  description?: string;
+};
+
+function isResourceEmpty(resource: SDKJSON.Resource) {
+  return Object.values(resource.methods).length < 1 && Object.values(resource.subresources ?? {}).length < 1;
+}
+
+function trimPath(path: string) {
+  return path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
+function apiHref(basePath: string, language: string, stainlessPath: string) {
+  const href = generateRoute(basePath, language, stainlessPath);
+  if (!href) return null;
+  return joinUrlParts(ASTRO_BASE, href, 'index.md');
+}
+
+function linkListItem(title: string, url: string, description?: string): Node {
+  const children = [md.link(url, title)];
+  if (description) children.push(md.text(`: ${description}`));
+  return md.item(md.inline(...children));
+}
+
+function generateProseIndex(routes: ProsePageEntry[], detailed: boolean) {
+  const pageEntryLink = (page: ProsePageEntry) =>
+    linkListItem(
+      page.title,
+      joinUrlParts(ASTRO_BASE, page.id === 'index' ? null : page.id, 'index.md'),
+      detailed ? page.description : undefined,
+    );
+  return [md.heading(2, 'Docs'), md.list(...routes.map(pageEntryLink))];
+}
+
+function renderMethods(basePath: string, language: string, methods: Record<string, SDKJSON.Method>) {
+  const output: Node[] = [];
+
+  for (const method of Object.values(methods)) {
+    const href = apiHref(basePath, language, method.stainlessPath);
+    if (href) output.push(linkListItem(method.title, href, method.summary));
+  }
+
+  return md.list(...output);
+}
+
+function renderResource(
+  basePath: string,
+  language: string,
+  detailed: boolean,
+  resource: SDKJSON.Resource,
+): Node {
+  const href = apiHref(basePath, language, resource.stainlessPath);
+  const output = [md.paragraph(href ? md.link(href, resource.title) : md.text(resource.title))];
+  if (resource.methods && detailed) output.push(renderMethods(basePath, language, resource.methods));
+  if (resource.subresources) output.push(renderSubs(basePath, language, detailed, resource.subresources));
+  return md.item(...output);
+}
+
+function renderSubs(
+  basePath: string,
+  language: string,
+  detailed: boolean,
+  resources: Record<string, SDKJSON.Resource>,
+): Node {
+  return md.list(
+    ...Object.values(resources)
+      .filter((res) => !isResourceEmpty(res))
+      .map((sub) => renderResource(basePath, language, detailed, sub)),
+  );
+}
+
+function renderLanguageNote(basePath: string, languages: string[]) {
+  return [
+    md.paragraph(
+      md.text('Links below point to language-neutral HTTP documentation. '),
+      md.text(
+        'SDK-specific docs follow the same URL structure with the language inserted after the base path: ',
+      ),
+      md.code(`${trimPath(basePath)}/{language}/resources/...`),
+      md.text('.'),
+    ),
+    md.paragraph(md.text(`Available languages: ${languages.join(', ')}`)),
+  ];
+}
+
+function generateRefIndex(
+  basePath: string,
+  languages: string[],
+  language: string,
+  detailed: boolean,
+  spec: SDKJSON.Spec,
+) {
+  const output = [md.heading(2, 'API Reference'), ...renderLanguageNote(basePath, languages)];
+
+  for (const resource of Object.values(spec.resources)) {
+    if (isResourceEmpty(resource)) continue;
+    const href = apiHref(basePath, language, resource.stainlessPath);
+    output.push(md.heading(3, [href ? md.link(href, resource.title) : md.text(resource.title)]));
+    if (resource.methods && detailed) output.push(renderMethods(basePath, language, resource.methods));
+    if (resource.subresources) output.push(renderSubs(basePath, language, detailed, resource.subresources));
+  }
+
+  return output;
+}
+
+function generateMarkdownIndex({
+  siteTitle,
+  description,
+  basePath,
+  languages,
+  spec,
+  detailed,
+  proseRoutes,
+}: {
+  siteTitle: string;
+  description: string | null;
+  basePath: string;
+  languages: string[];
+  spec: SDKJSON.Spec;
+  detailed: boolean;
+  proseRoutes: ProsePageEntry[];
+}) {
+  const output: Node[] = [md.heading(1, siteTitle)];
+  if (description) output.push(md.paragraph(md.text(description)));
+  if (proseRoutes.length > 0) output.push(...generateProseIndex(proseRoutes, detailed));
+  if (languages.length > 0) output.push(...generateRefIndex(basePath, languages, 'http', detailed, spec));
+
+  const doc = new Markdoc.Ast.Node('document', {}, output);
+  return Markdoc.format(doc);
+}
+
+export const GET: APIRoute = async () => {
+  const [docsCollection, spec] = await Promise.all([getCollection('docs'), getSDKJSONInSSR('http')]);
+  const apiEntries = [...walkTree(spec)].filter((n) => n.data.kind !== 'model');
+  const proseRoutes = docsCollection.map((entry) => ({
+    id: entry.id,
+    title: entry.data.title,
+    description: entry.data.description,
+  }));
+
+  const content = generateMarkdownIndex({
+    siteTitle: SITE_TITLE,
+    description: LLMS_TXT_DESCRIPTION,
+    basePath: API_REFERENCE_BASE_PATH,
+    languages: spec.docs?.languages ?? [],
+    detailed: apiEntries.length + proseRoutes.length < LLMS_TXT_DETAIL_THRESHOLD,
+    spec,
+    proseRoutes,
+  });
+
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};

package/plugin/routes/markdown.ts

@@ -1,13 +1,14 @@
 import type { APIRoute, GetStaticPaths } from 'astro';
-import { cmsClient } from '../cms/client';
-import { generateDocsRoutes, getReadmeContent } from '../react/Routing';
-import { getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { getReadmeContent } from '../react/Routing';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 
-import { renderMarkdown } from '@stainless-api/docs-ui/src/markdown';
+import { renderMarkdown } from '@stainless-api/docs-ui/markdown';
 
-import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type { EnvironmentType } from '@stainless-api/docs-ui/src/markdown/utils';
+import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type { EnvironmentType } from '@stainless-api/docs-ui/markdown/utils';
 import { PROPERTY_SETTINGS, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
+import { generateAllDocsRoutes } from '../helpers/generateDocsRoutes';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
 
 type RouteProps = {
   stainlessPath: string;
@@ -16,17 +17,17 @@ type RouteProps = {
 };
 
 export const getStaticPaths = (async () => {
-  const spec = await cmsClient.getSpec();
-  return generateDocsRoutes(spec);
+  const paths = await generateAllDocsRoutes();
+  return paths;
 }) satisfies GetStaticPaths;
 
 export const GET: APIRoute<RouteProps> = async ({ props }) => {
-  const spec = await cmsClient.getSpec();
+  const spec = await getSDKJSONInSSR(props.language);
 
   if (props.kind === 'readme') {
     const readmeContent = await getReadmeContent(spec, props.language);
     return new Response(readmeContent, {
-      headers: { 'Content-Type': 'text/markdown' },
+      headers: { 'Content-Type': 'text/plain' },
     });
   }
 
@@ -47,11 +48,11 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
     },
   };
 
-  const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method] : resource;
+  const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method]! : resource;
   const output = renderMarkdown(env, target);
 
   return new Response(output, {
-    headers: { 'Content-Type': 'text/markdown' },
+    headers: { 'Content-Type': 'text/plain' },
   });
 };