@stainless-api/docs 0.1.0-beta.132 → 0.1.0-beta.134
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/eslint-suppressions.json +0 -17
- package/package.json +17 -8
- package/plugin/components/SnippetCode.tsx +4 -35
- package/plugin/globalJs/copy.ts +1 -82
- package/plugin/index.ts +1 -116
- package/plugin/loadPluginConfig.ts +0 -7
- package/plugin/specs/generateSpec.ts +4 -5
- package/stl-docs/index.ts +6 -1
- package/stl-docs/loadStlDocsConfig.ts +7 -5
- package/stl-docs/og-image/components/OpenGraphFunctionSignature.tsx +64 -0
- package/stl-docs/og-image/components/OpenGraphImage.tsx +126 -0
- package/stl-docs/og-image/config.ts +56 -0
- package/stl-docs/og-image/image-gen/generate-api-reference-og-image.tsx +188 -0
- package/stl-docs/og-image/image-gen/generate-og-image.tsx +119 -0
- package/stl-docs/og-image/image-gen/get-logo-url.ts +47 -0
- package/stl-docs/og-image/index.ts +135 -0
- package/stl-docs/og-image/routes/add-og-image.ts +45 -0
- package/stl-docs/og-image/routes/get-api-reference-og-image.ts +36 -0
- package/stl-docs/og-image/routes/get-og-image.ts +28 -0
- package/stl-docs/og-image/theme.ts +43 -0
- package/stl-docs/og-image/utils.ts +14 -0
- package/stl-docs/schema-extension.ts +12 -0
- package/virtual-module.d.ts +17 -1
- package/playground-virtual-modules.d.ts +0 -96
- package/plugin/globalJs/create-playground.shim.ts +0 -3
- package/plugin/globalJs/playground-data.shim.ts +0 -1
- package/plugin/globalJs/playground-data.ts +0 -14
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
|
|
2
|
+
import path from 'path';
|
|
3
|
+
import { OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
|
|
4
|
+
import { renderOptions } from '../utils';
|
|
5
|
+
|
|
6
|
+
export const onRequest = defineRouteMiddleware((context) => {
|
|
7
|
+
const base = OG_IMAGE_OPTIONS?.basePath || '';
|
|
8
|
+
// Get the URL of the generated image for the current page using its ID and
|
|
9
|
+
// append the `.png` file extension.
|
|
10
|
+
const ogImageUrl = new URL(
|
|
11
|
+
path.posix.join(
|
|
12
|
+
import.meta.env.BASE_URL ?? '',
|
|
13
|
+
base,
|
|
14
|
+
'og',
|
|
15
|
+
`${context.locals.starlightRoute.id || 'index'}.png`,
|
|
16
|
+
),
|
|
17
|
+
context.site,
|
|
18
|
+
);
|
|
19
|
+
|
|
20
|
+
// Get the array of all tags to include in the `<head>` of the current page.
|
|
21
|
+
const { head } = context.locals.starlightRoute;
|
|
22
|
+
|
|
23
|
+
// Add the `<meta/>` tags for the Open Graph images.
|
|
24
|
+
head.push({
|
|
25
|
+
tag: 'meta',
|
|
26
|
+
attrs: { property: 'og:image', content: ogImageUrl.href },
|
|
27
|
+
});
|
|
28
|
+
head.push({
|
|
29
|
+
tag: 'meta',
|
|
30
|
+
attrs: { name: 'twitter:image', content: ogImageUrl.href },
|
|
31
|
+
});
|
|
32
|
+
head.push({
|
|
33
|
+
tag: 'meta',
|
|
34
|
+
attrs: { name: 'twitter:card', content: 'summary_large_image' },
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
head.push({
|
|
38
|
+
tag: 'meta',
|
|
39
|
+
attrs: { property: 'og:image:width', content: renderOptions.width.toString() },
|
|
40
|
+
});
|
|
41
|
+
head.push({
|
|
42
|
+
tag: 'meta',
|
|
43
|
+
attrs: { property: 'og:image:height', content: renderOptions.height.toString() },
|
|
44
|
+
});
|
|
45
|
+
});
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { generateAllDocsRoutes } from '@stainless-api/docs/generate-docs-routes';
|
|
2
|
+
import type { APIRoute } from 'astro';
|
|
3
|
+
import generateApiReferenceOgImage from '../image-gen/generate-api-reference-og-image';
|
|
4
|
+
import { notFoundResponse } from '../utils';
|
|
5
|
+
import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
|
|
6
|
+
|
|
7
|
+
const routes = await generateAllDocsRoutes();
|
|
8
|
+
|
|
9
|
+
export function getStaticPaths() {
|
|
10
|
+
return routes.map((route) => ({
|
|
11
|
+
params: { slug: `${route.params.slug}` },
|
|
12
|
+
...route.props,
|
|
13
|
+
}));
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export const GET: APIRoute = async ({ params }) => {
|
|
17
|
+
const slug = params?.slug;
|
|
18
|
+
if (!slug) return notFoundResponse();
|
|
19
|
+
|
|
20
|
+
// Remove slashes from the start and end of RESOLVED_API_REFERENCE_PATH
|
|
21
|
+
const apiBasePath = RESOLVED_API_REFERENCE_PATH?.replace(/^\/|\/$/g, '');
|
|
22
|
+
|
|
23
|
+
const slugWithoutBasePath = apiBasePath
|
|
24
|
+
? slug.startsWith(`${apiBasePath}/`)
|
|
25
|
+
? slug.slice(apiBasePath.length + 1)
|
|
26
|
+
: slug
|
|
27
|
+
: slug;
|
|
28
|
+
|
|
29
|
+
const apiReferenceRoute = routes.find((r) => r.params.slug === slugWithoutBasePath);
|
|
30
|
+
|
|
31
|
+
if (apiReferenceRoute) {
|
|
32
|
+
return generateApiReferenceOgImage({ apiReferenceRoute, slug });
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
return notFoundResponse();
|
|
36
|
+
};
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { getCollection } from 'astro:content';
|
|
2
|
+
import type { APIRoute } from 'astro';
|
|
3
|
+
import generateOgImage from '../image-gen/generate-og-image';
|
|
4
|
+
import { notFoundResponse } from '../utils';
|
|
5
|
+
|
|
6
|
+
const entries = await getCollection('docs');
|
|
7
|
+
// Map the entry array to an object with the page ID as key and the
|
|
8
|
+
// frontmatter data as value.
|
|
9
|
+
const pages = Object.fromEntries(entries.map(({ data, id }) => [id, { data }]));
|
|
10
|
+
|
|
11
|
+
export function getStaticPaths() {
|
|
12
|
+
const prosePaths = entries.map((entry) => ({
|
|
13
|
+
params: { slug: entry.id },
|
|
14
|
+
}));
|
|
15
|
+
return [...prosePaths];
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export const GET: APIRoute = async ({ params }) => {
|
|
19
|
+
const slug = params?.slug;
|
|
20
|
+
if (!slug) return notFoundResponse();
|
|
21
|
+
const page = pages[slug];
|
|
22
|
+
|
|
23
|
+
if (page) {
|
|
24
|
+
return generateOgImage({ slug, page });
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
return notFoundResponse();
|
|
28
|
+
};
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
const lightThemeVars = {
|
|
2
|
+
background: '#ffffffff',
|
|
3
|
+
foreground: '#262626ff',
|
|
4
|
+
foregroundReduced: `#262626cc`,
|
|
5
|
+
foregroundMuted: `#26262666`,
|
|
6
|
+
green: '#16a34a',
|
|
7
|
+
greenBackground: '#16a34a14',
|
|
8
|
+
blue: '#155dfc',
|
|
9
|
+
blueBackground: '#155dfc14',
|
|
10
|
+
orange: '#ea580c',
|
|
11
|
+
orangeBackground: '#ea580c14',
|
|
12
|
+
red: '#d01e22',
|
|
13
|
+
redBackground: '#d01e2214',
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
const darkThemeVars = {
|
|
17
|
+
background: '#0a0a0aff',
|
|
18
|
+
foreground: '#ffffffff',
|
|
19
|
+
foregroundReduced: `#ffffffcc`,
|
|
20
|
+
foregroundMuted: `#ffffff66`,
|
|
21
|
+
green: '#22c55e',
|
|
22
|
+
greenBackground: '#22c55e27',
|
|
23
|
+
blue: '#2b7fff',
|
|
24
|
+
blueBackground: '#2b80ff27',
|
|
25
|
+
orange: '#f97316',
|
|
26
|
+
orangeBackground: '#f9731627',
|
|
27
|
+
red: '#d01e22',
|
|
28
|
+
redBackground: '#d01e2227',
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const typography = {
|
|
32
|
+
baseFontSize: '40px',
|
|
33
|
+
baseLineHeight: '150%',
|
|
34
|
+
baseLetterSpacing: '-2%',
|
|
35
|
+
headerFontSize: '56px',
|
|
36
|
+
headerLineHeight: '120%',
|
|
37
|
+
headerLetterSpacing: '-3%',
|
|
38
|
+
breadcrumbFontSize: '32px',
|
|
39
|
+
breadcrumbLineHeight: '120%',
|
|
40
|
+
breadcrumbLetterSpacing: '-1%',
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
export { lightThemeVars, darkThemeVars, typography };
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { ImageResponseOptions } from '@takumi-rs/image-response';
|
|
2
|
+
import { OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
|
|
3
|
+
|
|
4
|
+
const defaultRenderOptions: ImageResponseOptions & { width: number; height: number } = {
|
|
5
|
+
width: 1200,
|
|
6
|
+
height: 630,
|
|
7
|
+
};
|
|
8
|
+
|
|
9
|
+
export const renderOptions = {
|
|
10
|
+
...defaultRenderOptions,
|
|
11
|
+
...OG_IMAGE_OPTIONS?.renderOptions,
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
export const notFoundResponse = () => new Response('Not found', { status: 404 });
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { z } from 'astro/zod';
|
|
2
|
+
|
|
3
|
+
export const stainlessDocsSchemaExtension = z.object({
|
|
4
|
+
ogImageOptions: z
|
|
5
|
+
.object({
|
|
6
|
+
logo: z.string().optional(),
|
|
7
|
+
theme: z.enum(['light', 'dark']).default('light'),
|
|
8
|
+
title: z.string().optional(),
|
|
9
|
+
description: z.string().optional(),
|
|
10
|
+
})
|
|
11
|
+
.optional(),
|
|
12
|
+
});
|
package/virtual-module.d.ts
CHANGED
|
@@ -15,7 +15,6 @@ declare module 'virtual:stl-starlight-virtual-module' {
|
|
|
15
15
|
export const CONTENT_PANEL_LAYOUT: 'double-pane' | 'single-pane';
|
|
16
16
|
export const EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: boolean | undefined;
|
|
17
17
|
export const EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS: boolean | undefined;
|
|
18
|
-
export const EXPERIMENTAL_PLAYGROUNDS: boolean | undefined;
|
|
19
18
|
export const EXPERIMENTAL_REQUEST_BUILDER: boolean | undefined;
|
|
20
19
|
export const PROPERTY_SETTINGS: PropertySettingsType;
|
|
21
20
|
export const MIDDLEWARE: StlStarlightMiddleware;
|
|
@@ -99,5 +98,22 @@ declare module 'virtual:stl-starlight-reference-sidebars' {
|
|
|
99
98
|
export const sidebars: GeneratedSidebarDef[];
|
|
100
99
|
}
|
|
101
100
|
|
|
101
|
+
declare module 'virtual:stainless-docs/docs-og-image' {
|
|
102
|
+
import type { StarlightUserConfig } from '@astrojs/starlight/types';
|
|
103
|
+
|
|
104
|
+
export const LOGO: StarlightUserConfig['logo'];
|
|
105
|
+
export const OG_IMAGE_OPTIONS: import('./stl-docs/og-image/config').OGImageConfig | undefined;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
declare module 'virtual:stainless-docs/docs-og-image/components/OpenGraphImage' {
|
|
109
|
+
const OpenGraphImage: typeof import('./stl-docs/og-image/components/OpenGraphImage').default;
|
|
110
|
+
export default OpenGraphImage;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
declare module 'virtual:stainless-docs/docs-og-image/components/OpenGraphFunctionSignature' {
|
|
114
|
+
const OpenGraphFunctionSignature: typeof import('./stl-docs/og-image/components/OpenGraphFunctionSignature').default;
|
|
115
|
+
export default OpenGraphFunctionSignature;
|
|
116
|
+
}
|
|
117
|
+
|
|
102
118
|
declare const __STLDOCS_HAS_API_REFERENCE__: boolean;
|
|
103
119
|
declare const __STLDOCS_ENABLE_AI_CHAT__: boolean;
|
|
@@ -1,96 +0,0 @@
|
|
|
1
|
-
declare module 'virtual:stl-playground/typescript.json' {
|
|
2
|
-
const data: {
|
|
3
|
-
links: [string, string][];
|
|
4
|
-
files: [string, string][];
|
|
5
|
-
} | null;
|
|
6
|
-
export { data as default };
|
|
7
|
-
}
|
|
8
|
-
declare module 'virtual:stl-playground/python.json' {
|
|
9
|
-
const data: { files: Record<string, string>; wheel: string } | null;
|
|
10
|
-
export { data as default };
|
|
11
|
-
}
|
|
12
|
-
declare module 'virtual:stl-playground/auth.json' {
|
|
13
|
-
const data:
|
|
14
|
-
| ({
|
|
15
|
-
type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
|
|
16
|
-
description?: string;
|
|
17
|
-
name: string;
|
|
18
|
-
title: string;
|
|
19
|
-
header: string | undefined;
|
|
20
|
-
example: string | undefined;
|
|
21
|
-
} & {
|
|
22
|
-
opts: {
|
|
23
|
-
name: string;
|
|
24
|
-
type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
|
|
25
|
-
nullable: boolean;
|
|
26
|
-
description?: string | undefined;
|
|
27
|
-
example?: unknown;
|
|
28
|
-
default?: unknown;
|
|
29
|
-
read_env?: string | undefined;
|
|
30
|
-
auth?:
|
|
31
|
-
| {
|
|
32
|
-
security_scheme: string;
|
|
33
|
-
role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
|
|
34
|
-
}
|
|
35
|
-
| undefined;
|
|
36
|
-
}[];
|
|
37
|
-
})[]
|
|
38
|
-
| null;
|
|
39
|
-
export { data as default };
|
|
40
|
-
}
|
|
41
|
-
declare module 'virtual:stl-playground/data' {
|
|
42
|
-
import type { Config } from 'virtual:stl-playground/create';
|
|
43
|
-
declare const data: Config;
|
|
44
|
-
export { data as default };
|
|
45
|
-
}
|
|
46
|
-
declare module 'virtual:stl-playground/create' {
|
|
47
|
-
export type PlaygroundLanguage = 'python' | 'typescript' | 'http';
|
|
48
|
-
export type Config = {
|
|
49
|
-
wheelUrl: string;
|
|
50
|
-
pyTypes: {
|
|
51
|
-
files: Record<string, string>;
|
|
52
|
-
wheel: string;
|
|
53
|
-
} | null;
|
|
54
|
-
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
55
|
-
HIGHLIGHT_THEMES: any;
|
|
56
|
-
tsTypes: {
|
|
57
|
-
links: [string, string][];
|
|
58
|
-
files: [string, string][];
|
|
59
|
-
} | null;
|
|
60
|
-
authData:
|
|
61
|
-
| ({
|
|
62
|
-
type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
|
|
63
|
-
description?: string;
|
|
64
|
-
name: string;
|
|
65
|
-
title: string;
|
|
66
|
-
header: string | undefined;
|
|
67
|
-
example: string | undefined;
|
|
68
|
-
} & {
|
|
69
|
-
opts: {
|
|
70
|
-
name: string;
|
|
71
|
-
type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
|
|
72
|
-
nullable: boolean;
|
|
73
|
-
description?: string | undefined;
|
|
74
|
-
example?: unknown;
|
|
75
|
-
default?: unknown;
|
|
76
|
-
read_env?: string | undefined;
|
|
77
|
-
auth?:
|
|
78
|
-
| {
|
|
79
|
-
security_scheme: string;
|
|
80
|
-
role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
|
|
81
|
-
}
|
|
82
|
-
| undefined;
|
|
83
|
-
}[];
|
|
84
|
-
})[]
|
|
85
|
-
| null;
|
|
86
|
-
};
|
|
87
|
-
export function createPlayground(
|
|
88
|
-
props: {
|
|
89
|
-
lang: PlaygroundLanguage;
|
|
90
|
-
doc: string;
|
|
91
|
-
/** div.stl-snippet-request-container */
|
|
92
|
-
container: HTMLElement;
|
|
93
|
-
onLanguageSelect: (value: string) => void;
|
|
94
|
-
} & Config,
|
|
95
|
-
): () => Promise<void>;
|
|
96
|
-
}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export default {};
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
import wheelUrl from 'virtual:stl-playground/python/wheel.whl?url';
|
|
2
|
-
import pyTypes from 'virtual:stl-playground/python.json';
|
|
3
|
-
import tsTypes from 'virtual:stl-playground/typescript.json';
|
|
4
|
-
import authData from 'virtual:stl-playground/auth.json';
|
|
5
|
-
import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
|
|
6
|
-
import { Config } from 'virtual:stl-playground/create';
|
|
7
|
-
|
|
8
|
-
export default {
|
|
9
|
-
wheelUrl,
|
|
10
|
-
pyTypes,
|
|
11
|
-
tsTypes,
|
|
12
|
-
authData,
|
|
13
|
-
HIGHLIGHT_THEMES,
|
|
14
|
-
} satisfies Config;
|