@stainless-api/docs 0.1.0-beta.0

package/plugin/routes/Docs.astro

@@ -0,0 +1,171 @@
+---
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import { cmsClient } from "../cms/client";
+
+import "@stainless-api/docs-ui/src/styles/resets.css";
+import "@stainless-api/docs-ui/src/styles/primitives.css";
+import "@stainless-api/docs-ui/src/styles/main.css";
+import "@stainless-api/docs-ui/src/styles/snippets.css";
+// TODO: fix variables.css import
+// import "./variables.css";
+
+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";
+
+
+const spec = await cmsClient.getSpec();
+const routes = generateDocsRoutes(spec);
+
+const route = routes.find((r) => r.params.slug === Astro.params.slug);
+
+if (!route) {
+  throw new Error("No such route");
+}
+
+const readmeContent = await getReadmeContent(spec, route.props.language);
+const readme =
+  route.props.kind === "readme"
+    ? await astroMarkdownRender(readmeContent ?? "")
+    : null;
+
+const resource = route.props.stainlessPath
+  ? getResourceFromSpec(route.props.stainlessPath, spec)
+  : null;
+
+const pageNav =
+  route.props.kind === "resource" && resource
+    ? buildPageNavigation(resource)
+    : route.props.kind === "readme" && readme?.metadata
+      ? readme?.metadata.headings
+      : [];
+
+const props = route.props;
+
+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";
+}
+
+---
+
+
+<StarlightPage
+  headings={pageNav}
+  frontmatter={{
+    title: props?.title,
+    head: [
+      {
+        tag: "link",
+        attrs: {
+          rel: "alternate",
+          type: "text/markdown",
+          href: `${BASE_PATH}/${Astro.params.slug}.md`
+        }
+      }
+    ],
+    pagefind: false,
+    tableOfContents: ["resource", "readme"].includes(props.kind)
+      ? { maxHeadingLevel: 6 }
+      : false,
+    // @ts-ignore
+    stainlessStarlight: {
+      basePath: BASE_PATH,
+      ...props,
+    },
+  }}
+>
+  {
+    resource && props.stainlessPath && props.kind ? (
+      <div class="not-content">
+        <RenderSpec
+          spec={spec}
+          kind={props.kind}
+          path={props.stainlessPath}
+          language={props.language}
+          currentPath={Astro.url.pathname}
+          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>
+      </>
+    )
+  }
+</StarlightPage>
+
+<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>

package/plugin/routes/DocsStatic.astro

@@ -0,0 +1,14 @@
+---
+import type { GetStaticPaths } from 'astro';
+import Docs from './Docs.astro';
+import { cmsClient } from '../cms/client';
+import { generateDocsRoutes } from '../react/Routing';
+
+export const getStaticPaths = (async () => {
+  const spec = await cmsClient.getSpec();
+  const routes = generateDocsRoutes(spec);
+  return routes;
+}) satisfies GetStaticPaths;
+---
+
+<Docs />

package/plugin/routes/Overview.astro

@@ -0,0 +1,67 @@
+---
+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 '@stainless-api/docs-ui/src/styles/resets.css';
+import '@stainless-api/docs-ui/src/styles/primitives.css';
+import '@stainless-api/docs-ui/src/styles/main.css';
+import '@stainless-api/docs-ui/src/styles/snippets.css';
+// TODO: fix variables.css import
+// import '../components/variables.css';
+import { RenderLibraries, RenderSpecOverview, type SpecMetadata } from '../react/Routing';
+
+const spec = await cmsClient.getSpec();
+
+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;
+---
+
+<StarlightPage
+  frontmatter={{
+    title: 'API Reference',
+    pagefind: false,
+    tableOfContents: false,
+    stainlessStarlight: {
+      basePath: BASE_PATH,
+      language: 'http',
+    },
+  }}
+>
+  <h3>Libraries</h3>
+
+  <div class="stldocs-root language-blocks stl-ui-not-prose">
+    <RenderLibraries metadata={metadata} />
+  </div>
+
+  <h3>API Overview</h3>
+
+  <div class="stldocs-root api-overview stl-ui-not-prose">
+    <RenderSpecOverview spec={spec} language="http" />
+  </div>
+</StarlightPage>
+
+<style>
+  .language-blocks {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1rem;
+    margin-top: 2rem;
+
+    .stldocs-language-block {
+      width: 350px;
+    }
+  }
+
+  .api-overview {
+    .stldocs-resource-content {
+      padding: 0 !important;
+    }
+  }
+</style>
+
+<script src="../globalJs/copy.ts"></script>

package/plugin/routes/markdown.ts

@@ -0,0 +1,58 @@
+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 { renderMarkdown } from '@stainless-api/docs-ui/src/markdown';
+
+import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type { EnvironmentType } from '@stainless-api/docs-ui/src/markdown/utils';
+import { PROPERTY_SETTINGS, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
+
+type RouteProps = {
+  stainlessPath: string;
+  language: DocsLanguage;
+  kind: 'http_method' | 'resource' | 'readme';
+};
+
+export const getStaticPaths = (async () => {
+  const spec = await cmsClient.getSpec();
+  return generateDocsRoutes(spec);
+}) satisfies GetStaticPaths;
+
+export const GET: APIRoute<RouteProps> = async ({ props }) => {
+  const spec = await cmsClient.getSpec();
+
+  if (props.kind === 'readme') {
+    const readmeContent = await getReadmeContent(spec, props.language);
+    return new Response(readmeContent, {
+      headers: { 'Content-Type': 'text/markdown' },
+    });
+  }
+
+  const parsed = parseStainlessPath(props.stainlessPath);
+  const resource = getResourceFromSpec(props.stainlessPath, spec);
+
+  if (!resource) throw new Error('Invalid route');
+
+  const env: EnvironmentType = {
+    spec,
+    language: props.language,
+    options: {
+      renderNestedResources: true,
+      includeModelProperties: PROPERTY_SETTINGS.includeModelProperties,
+    },
+    transforms: {
+      transformRequestSnippet: MIDDLEWARE.transformRequestSnippet,
+    },
+  };
+
+  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' },
+  });
+};
+
+export const prerender = true;