chore(docs): add example snippets (#1101)

jasonkuhrt · Sep 17, 2024 · e706f51 · e706f51
1 parent 507637d
commit e706f51
Show file tree

Hide file tree

Showing 86 changed files with 3,560 additions and 182 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,3 @@ tsconfig.vitest-temp.json
 website/.vitepress/dist
 website/.vitepress/cache
 legacy
-.vitepress
diff --git a/...__outputs__/10_transport-http/transport-http_extension_headers__dynamicHeaders.output.txt b/...__outputs__/10_transport-http/transport-http_extension_headers__dynamicHeaders.output.txt
@@ -4,7 +4,7 @@
   headers: Headers {
     accept: 'application/graphql-response+json; charset=utf-8, application/json; charset=utf-8',
     'content-type': 'application/json',
-    'x-sent-at-time': '1726587622992'
+    'x-sent-at-time': '1726596325884'
   },
   signal: undefined,
   method: 'post',

diff --git a/examples/__outputs__/20_output/output_envelope.output.txt b/examples/__outputs__/20_output/output_envelope.output.txt
@@ -19,7 +19,7 @@
     headers: Headers {
       connection: 'keep-alive',
       'content-length': '119',
-      'x-served-by': 'cache-yul1970028-YUL',
+      'x-served-by': 'cache-yul1970046-YUL',
       'accept-ranges': 'bytes',
       date: 'Sun, 08 Sep 2024 18:13:26 GMT',
       'content-type': 'application/graphql-response+json; charset=utf-8',
@@ -32,13 +32,13 @@
       'alt-svc': 'h3=":443"; ma=86400',
       'access-control-allow-origin': '*',
       'x-powered-by': 'Stellate',
-      age: '768418',
+      age: '777121',
       'cache-control': 'public, s-maxage=2628000, stale-while-revalidate=2628000',
       'x-cache': 'HIT',
-      'x-cache-hits': '99',
+      'x-cache-hits': '87',
       'gcdn-cache': 'HIT',
-      'stellate-rate-limit-budget-remaining': '41',
-      'stellate-rate-limit-rules': '"IP limit";type="RequestCount";budget=50;limited=?0;remaining=41;refill=60',
+      'stellate-rate-limit-budget-remaining': '48',
+      'stellate-rate-limit-rules': '"IP limit";type="RequestCount";budget=50;limited=?0;remaining=48;refill=60',
       'stellate-rate-limit-decision': 'pass',
       'stellate-rate-limit-budget-required': '5',
       'content-encoding': 'br'

diff --git a/examples/__outputs__/60_extension/extension_opentelemetry__opentelemetry.output.txt b/examples/__outputs__/60_extension/extension_opentelemetry__opentelemetry.output.txt
@@ -9,14 +9,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '74881568a3d7d3c86f1657709c86b4a0',
-  parentId: 'f3a059903360f365',
+  traceId: '0c3328523947fd9b3201120e5b4cb4a0',
+  parentId: 'ddcee8d1f8d74086',
   traceState: undefined,
   name: 'encode',
-  id: '5219af43fdf80466',
+  id: '045b80da91d65b9d',
   kind: 0,
-  timestamp: 1726587623552000,
-  duration: 542.375,
+  timestamp: 1726596326575000,
+  duration: 1290.958,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -33,14 +33,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '74881568a3d7d3c86f1657709c86b4a0',
-  parentId: 'f3a059903360f365',
+  traceId: '0c3328523947fd9b3201120e5b4cb4a0',
+  parentId: 'ddcee8d1f8d74086',
   traceState: undefined,
   name: 'pack',
-  id: '063a4b532a0241a3',
+  id: '0854613b629f13f6',
   kind: 0,
-  timestamp: 1726587623556000,
-  duration: 1065.958,
+  timestamp: 1726596326600000,
+  duration: 1107.5,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -57,14 +57,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '74881568a3d7d3c86f1657709c86b4a0',
-  parentId: 'f3a059903360f365',
+  traceId: '0c3328523947fd9b3201120e5b4cb4a0',
+  parentId: 'ddcee8d1f8d74086',
   traceState: undefined,
   name: 'exchange',
-  id: 'f5b369b304e991b6',
+  id: '1a8a5ce00ea500ed',
   kind: 0,
-  timestamp: 1726587623558000,
-  duration: 148649.083,
+  timestamp: 1726596326602000,
+  duration: 416840.875,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -81,14 +81,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '74881568a3d7d3c86f1657709c86b4a0',
-  parentId: 'f3a059903360f365',
+  traceId: '0c3328523947fd9b3201120e5b4cb4a0',
+  parentId: 'ddcee8d1f8d74086',
   traceState: undefined,
   name: 'unpack',
-  id: '0e527bfe6c4088cd',
+  id: '79fc98db2f26ecb0',
   kind: 0,
-  timestamp: 1726587623707000,
-  duration: 2221.792,
+  timestamp: 1726596327019000,
+  duration: 2409.542,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -105,14 +105,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '74881568a3d7d3c86f1657709c86b4a0',
-  parentId: 'f3a059903360f365',
+  traceId: '0c3328523947fd9b3201120e5b4cb4a0',
+  parentId: 'ddcee8d1f8d74086',
   traceState: undefined,
   name: 'decode',
-  id: '8abb47d1d55ae667',
+  id: '5785c002db424547',
   kind: 0,
-  timestamp: 1726587623709000,
-  duration: 122.375,
+  timestamp: 1726596327022000,
+  duration: 126.584,
   attributes: {},
   status: { code: 0 },
   events: [],
@@ -129,14 +129,14 @@
     }
   },
   instrumentationScope: { name: 'graffle', version: undefined, schemaUrl: undefined },
-  traceId: '74881568a3d7d3c86f1657709c86b4a0',
+  traceId: '0c3328523947fd9b3201120e5b4cb4a0',
   parentId: undefined,
   traceState: undefined,
   name: 'request',
-  id: 'f3a059903360f365',
+  id: 'ddcee8d1f8d74086',
   kind: 0,
-  timestamp: 1726587623552000,
-  duration: 157809.333,
+  timestamp: 1726596326573000,
+  duration: 448707.334,
   attributes: {},
   status: { code: 0 },
   events: [],

diff --git a/scripts/generate-examples-derivatives/generate-docs.ts b/scripts/generate-examples-derivatives/generate-docs.ts
@@ -4,6 +4,15 @@ import { documentQueryContinents, publicGraphQLSchemaEndpoints } from '../../exa
 import { deleteFiles } from '../lib/deleteFiles.js'
 import { computeCombinations, type Example } from './helpers.js'
 
+interface ExampleTransformed extends Example {
+  snippet: {
+    content: string
+  }
+  snippetDetail: {
+    content: string
+  }
+}
+
 export const generateDocs = async (examples: Example[]) => {
   const examplesTransformed = examples
     .map(transformOther)
@@ -12,42 +21,70 @@ export const generateDocs = async (examples: Example[]) => {
     .map(transformOther)
     .map(transformMarkdown)
 
-  /**
-   * Write Example Pages
-   * -------------------
-   */
+  await Promise.all([
+    generateExampleSnippets(examplesTransformed),
+    generateExamplePages(examplesTransformed),
+    generateExampleLinksSnippets(examplesTransformed),
+  ])
+}
 
-  // Delete all existing to handle case of renaming or deleting examples.
-  await deleteFiles({
-    pattern: `./website/content/examples/**/*`,
-    options: { ignore: [`./website/content/examples/index.md`] },
-  })
+/**
+ * Define Generators
+ * -----------------
+ */
 
+const generateExampleSnippets = async (examplesTransformed: ExampleTransformed[]) => {
+  const exampleGroups = Object.values(groupBy(examplesTransformed, example => example.group.dirName))
   {
-    const groups = Object.values(groupBy(examplesTransformed, example => example.group.dirName))
-
+    // Delete all existing to handle case of renaming or deleting examples.
+    await deleteFiles({
+      pattern: `./website/content/_snippets/examples/**/*.md`,
+    })
     await Promise.all(
-      groups.map(async (examples) => {
-        const groupName = examples[0]!.group.dirName
-        await FS.mkdir(`./website/content/examples/${groupName}`, { recursive: true })
+      exampleGroups.map(async (examples) => {
+        const groupName = examples[0]!.group.humanName
+        await FS.mkdir(`./website/content/_snippets/examples/${groupName}`, { recursive: true })
         await Promise.all(examples.map(async (example) => {
-          const exampleMarkdownFilePath =
-            `./website/content/examples/${example.group.dirName}/${example.fileName.canonical}.md`
-          await FS.writeFile(exampleMarkdownFilePath, example.file.content)
-          console.log(`Generated example doc in markdown at`, exampleMarkdownFilePath)
+          const snippetFilePath = `./website/content/_snippets/examples/${groupName}/${example.fileName.canonical}.md`
+          const snippetDetailFilePath =
+            `./website/content/_snippets/examples/${groupName}/${example.fileName.canonical}.detail.md`
+          await Promise.all([
+            FS.writeFile(snippetFilePath, example.snippet.content),
+            FS.writeFile(snippetDetailFilePath, example.snippetDetail.content),
+          ])
+          console.log(`Generated example doc snippet in markdown at`, snippetFilePath)
         }))
       }),
     )
   }
 
-  console.log(`Generated a Vitepress page for each example.`)
+  console.log(`Generated a Vitepress snippet for each example.`)
+}
 
-  /**
-   * Write Example Links Page Partials
-   * ---------------------------------
-   */
-  // todo
+const generateExamplePages = async (examplesTransformed: ExampleTransformed[]) => {
+  const exampleGroups = Object.values(groupBy(examplesTransformed, example => example.group.dirName))
 
+  // Delete all existing to handle case of renaming or deleting examples.
+  await deleteFiles({
+    pattern: `./website/content/examples/**/*`,
+    options: { ignore: [`./website/content/examples/index.md`] },
+  })
+
+  await Promise.all(
+    exampleGroups.map(async (examples) => {
+      const groupName = examples[0]!.group.dirName
+      await FS.mkdir(`./website/content/examples/${groupName}`, { recursive: true })
+      await Promise.all(examples.map(async (example) => {
+        const exampleMarkdownFilePath = `./website/content/examples/${groupName}/${example.fileName.canonical}.md`
+        await FS.writeFile(exampleMarkdownFilePath, example.file.content)
+        console.log(`Generated example doc page in markdown at`, exampleMarkdownFilePath)
+      }))
+    }),
+  )
+  console.log(`Generated a Vitepress page for each example.`)
+}
+
+const generateExampleLinksSnippets = async (examplesTransformed: ExampleTransformed[]) => {
   // Delete all existing to handle case of renaming or deleting examples.
   await deleteFiles({ pattern: `./website/content/_snippets/example-links/*.md` })
 
@@ -189,32 +226,57 @@ ${block}
 `.trim()
   }).join(`\n`)
 
-  const outputs = outputBlocks.length > 0
-    ? `
+  const codeBlock = `
+<!-- dprint-ignore-start -->
+\`\`\`ts twoslash
+${example.file.content.trim()}
+\`\`\`
+<!-- dprint-ignore-end -->
+  `.trim()
+
+  const outputs = outputBlocks.length === 0
+    ? ``
+    : `
 #### Outputs
 
 ${outputBlocks}
 `.trim()
-    : ``
 
-  const source = `
+  const newContent = `
 ---
 aside: false
 ---
 
 # ${example.fileName.canonicalTitle}${example.description ? `\n\n${example.description}\n` : ``}
 
-<!-- dprint-ignore-start -->
-\`\`\`ts twoslash
-${example.file.content.trim()}
-\`\`\`
-<!-- dprint-ignore-end -->
+${codeBlock}
+
+${outputs}
 `.trim()
 
-  const newContent = [source, outputs].filter(_ => _ !== ``).join(`\n\n`)
+  const snippet = {
+    content: `
+<div class="ExampleSnippet">
+<a href="../../examples/${example.group.humanName}/${example.fileName.canonical}">${example.fileName.canonicalTitle}</a>
+
+${[codeBlock, outputBlocks].filter(_ => _ !== ``).join(`\n\n`).trim()}
+
+</div>
+    `.trim(),
+  }
+
+  const snippetDetail = {
+    content: `
+::: details Example
+${snippet.content}
+:::
+    `.trim(),
+  }
 
   return {
     ...example,
+    snippet,
+    snippetDetail,
     file: {
       ...example.file,
       content: newContent,

diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts
@@ -2,7 +2,8 @@ import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 import { capitalize } from 'es-toolkit'
 import { ModuleKind, ModuleResolutionKind } from 'typescript'
 import { defineConfig } from 'vitepress'
-import { generateSidebar, Sidebar, SidebarItem, SidebarMulti, SidebarMultiItem } from 'vitepress-sidebar'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
+import { generateSidebar, SidebarItem, SidebarMulti } from 'vitepress-sidebar'
 
 const prefixPattern = /\d+_/g
 
@@ -95,6 +96,9 @@ export default defineConfig({
     }],
   ],
   markdown: {
+    config(md) {
+      md.use(tabsMarkdownPlugin)
+    },
     codeTransformers: [
       transformerTwoslash({
         twoslashOptions: {

diff --git a/website/.vitepress/theme/components/GeneratedClientBadge.vue b/website/.vitepress/theme/components/GeneratedClientBadge.vue
@@ -0,0 +1,3 @@
+<template>
+	<Badge text="generated client" />
+</template>
diff --git a/website/.vitepress/theme/MyLayout.vue → .../.vitepress/theme/components/MyLayout.vue b/website/.vitepress/theme/MyLayout.vue → .../.vitepress/theme/components/MyLayout.vue
@@ -1,7 +1,5 @@
-<!--.vitepress/theme/MyLayout.vue-->
 <script setup>
 import DefaultTheme from 'vitepress/theme'
-
 const { Layout } = DefaultTheme
 </script>