add more examples to the site

gittgott · Jun 10, 2023 · c661c6c · c661c6c
1 parent e552c00
commit c661c6c
Show file tree

Hide file tree

Showing 37 changed files with 542 additions and 67 deletions.
diff --git a/scripts/generate-site-examples.js b/scripts/generate-site-examples.js
@@ -22,6 +22,61 @@ const CODE_BLOCK_END_REGEX = /\*\s*```/
 const COMMENT_LINE_REGEX = /\*\s*(.*)/
 const CODE_LINE_REGEX = /\*(.*)/
 
+const moreExamplesByCategory = {
+  select: {
+    'select method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#select',
+    'selectAll method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#selectAll',
+    'selectFrom method':
+      'https://kysely-org.github.io/kysely/classes/Kysely.html#selectFrom',
+  },
+  where: {
+    'where method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#where',
+    'whereRef method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#whereRef',
+  },
+  join: {
+    'innerJoin method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#innerJoin',
+    'leftJoin method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#leftJoin',
+    'rightJoin method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#rightJoin',
+    'fullJoin method':
+      'https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#fullJoin',
+  },
+  insert: {
+    'values method':
+      'https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#values',
+    'onConflict method':
+      'https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#onConflict',
+    'returning method':
+      'https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#returning',
+    'insertInto method':
+      'https://kysely-org.github.io/kysely/classes/Kysely.html#insertInto',
+  },
+  update: {
+    'set method':
+      'https://kysely-org.github.io/kysely/classes/UpdateQueryBuilder.html#set',
+    'returning method':
+      'https://kysely-org.github.io/kysely/classes/UpdateQueryBuilder.html#returning',
+    'updateTable method':
+      'https://kysely-org.github.io/kysely/classes/Kysely.html#updateTable',
+  },
+  delete: {
+    'deleteFrom method':
+      'https://kysely-org.github.io/kysely/classes/Kysely.html#deleteFrom',
+    'returning method':
+      'https://kysely-org.github.io/kysely/classes/DeleteQueryBuilder.html#returning',
+  },
+  transactions: {
+    'transaction method':
+      'https://kysely-org.github.io/kysely/classes/Kysely.html#transaction',
+  },
+}
+
 function main() {
   deleteAllExamples()
 
@@ -95,48 +150,81 @@ function writeSiteExample(state) {
   const [, category, name, priority] = state.annotation
   const code = trimEmptyLines(state.codeLines).join('\n')
   const comment = trimEmptyLines(state.commentLines).join('\n')
+  const codeVariable = _.camelCase(name)
 
   const fileName = `${priority.padStart(4, '0')}-${_.kebabCase(name)}`
-  const filePath = path.join(
-    SITE_EXAMPLE_PATH,
-    category.toUpperCase(),
-    fileName
-  )
+  const filePath = path.join(SITE_EXAMPLE_PATH, category, fileName)
 
-  const codeFile = `export const ${_.camelCase(name)} = \`${deindent(
-    code
-  ).replaceAll('`', '\\`').replaceAll('${', '\\${')}\``
+  const codeFile = `export const ${codeVariable} = \`${deindent(code)
+    .replaceAll('`', '\\`')
+    .replaceAll('${', '\\${')}\``
 
-  const exampleFileBegin = deindent(`
-    ---
-    title: '${name}'
-    ---
+  const parts = [
+    deindent(`
+      ---
+      title: '${name}'
+      ---
 
-    # ${name}
-  `)
+      # ${name}
+    `),
+  ]
 
-  const exampleFileEnd = deindent(`
-    import {
-      Playground,
-      exampleSetup,
-    } from '../../../src/components/Playground'
+  if (comment?.trim()) {
+    parts.push(comment, '')
+  }
 
-    import {
-      ${_.camelCase(name)}
-    } from './${fileName}'
+  parts.push(
+    deindent(`
+      import {
+        Playground,
+        exampleSetup,
+      } from '../../../src/components/Playground'
+
+      import {
+        ${codeVariable}
+      } from './${fileName}'
+
+      <div style={{ marginBottom: '1em' }}>
+        <Playground code={${codeVariable}} setupCode={exampleSetup} />
+      </div>
+    `)
+  )
 
-    <Playground code={${_.camelCase(name)}} setupCode={exampleSetup} />
-  `)
+  const moreExamples = buildMoreExamplesMarkdown(category)
+  if (moreExamples?.trim()) {
+    parts.push(moreExamples)
+  }
 
-  const exampleFile =
-    comment.trim().length === 0
-      ? [exampleFileBegin, exampleFileEnd].join('\n')
-      : [exampleFileBegin, comment, '', exampleFileEnd].join('\n')
+  const exampleFile = parts.join('\n')
 
   fs.writeFileSync(filePath + '.js', codeFile)
   fs.writeFileSync(filePath + '.mdx', exampleFile)
 }
 
+function buildMoreExamplesMarkdown(category) {
+  const links = moreExamplesByCategory[category]
+  if (!links) {
+    return undefined
+  }
+
+  const lines = [
+    ':::info More examples',
+    'The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)',
+    'but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always',
+    'just one hover away!',
+    '',
+    'For example, check out these sections:',
+  ]
+
+  for (const linkName of Object.keys(links)) {
+    lines.push(` - [${linkName}](${links[linkName]})`)
+  }
+
+  lines.push(':::')
+
+  return lines.join('\n')
+}
+
 function exitExample(state) {
   state.annotation = null
   state.inExample = false

diff --git a/site/docs/examples/DELETE/0010-single-row.mdx b/site/docs/examples/DELETE/0010-single-row.mdx
@@ -15,4 +15,16 @@ import {
   singleRow
 } from './0010-single-row'
 
-<Playground code={singleRow} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={singleRow} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [deleteFrom method](https://kysely-org.github.io/kysely/classes/Kysely.html#deleteFrom)
+ - [returning method](https://kysely-org.github.io/kysely/classes/DeleteQueryBuilder.html#returning)
+:::
diff --git a/site/docs/examples/DELETE/_category_.json b/site/docs/examples/DELETE/_category_.json
@@ -1,5 +1,5 @@
 {
-  "label": "DELETE",
+  "label": "Delete",
   "position": 6,
   "link": {
     "type": "generated-index",

diff --git a/site/docs/examples/INSERT/0010-single-row.mdx b/site/docs/examples/INSERT/0010-single-row.mdx
@@ -15,4 +15,18 @@ import {
   singleRow
 } from './0010-single-row'
 
-<Playground code={singleRow} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={singleRow} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [values method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#values)
+ - [onConflict method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#onConflict)
+ - [returning method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#returning)
+ - [insertInto method](https://kysely-org.github.io/kysely/classes/Kysely.html#insertInto)
+:::
diff --git a/site/docs/examples/INSERT/0020-multiple-rows.mdx b/site/docs/examples/INSERT/0020-multiple-rows.mdx
@@ -18,4 +18,18 @@ import {
   multipleRows
 } from './0020-multiple-rows'
 
-<Playground code={multipleRows} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={multipleRows} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [values method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#values)
+ - [onConflict method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#onConflict)
+ - [returning method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#returning)
+ - [insertInto method](https://kysely-org.github.io/kysely/classes/Kysely.html#insertInto)
+:::
diff --git a/site/docs/examples/INSERT/0030-returning-data.mdx b/site/docs/examples/INSERT/0030-returning-data.mdx
@@ -18,4 +18,18 @@ import {
   returningData
 } from './0030-returning-data'
 
-<Playground code={returningData} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={returningData} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [values method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#values)
+ - [onConflict method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#onConflict)
+ - [returning method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#returning)
+ - [insertInto method](https://kysely-org.github.io/kysely/classes/Kysely.html#insertInto)
+:::
diff --git a/site/docs/examples/INSERT/0040-complex-values.mdx b/site/docs/examples/INSERT/0040-complex-values.mdx
@@ -17,4 +17,18 @@ import {
   complexValues
 } from './0040-complex-values'
 
-<Playground code={complexValues} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={complexValues} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [values method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#values)
+ - [onConflict method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#onConflict)
+ - [returning method](https://kysely-org.github.io/kysely/classes/InsertQueryBuilder.html#returning)
+ - [insertInto method](https://kysely-org.github.io/kysely/classes/Kysely.html#insertInto)
+:::
diff --git a/site/docs/examples/INSERT/_category_.json b/site/docs/examples/INSERT/_category_.json
@@ -1,5 +1,5 @@
 {
-  "label": "INSERT",
+  "label": "Insert",
   "position": 4,
   "link": {
     "type": "generated-index",

diff --git a/site/docs/examples/JOIN/0010-simple-inner-join.mdx b/site/docs/examples/JOIN/0010-simple-inner-join.mdx
@@ -15,4 +15,18 @@ import {
   simpleInnerJoin
 } from './0010-simple-inner-join'
 
-<Playground code={simpleInnerJoin} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={simpleInnerJoin} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [innerJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#innerJoin)
+ - [leftJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#leftJoin)
+ - [rightJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#rightJoin)
+ - [fullJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#fullJoin)
+:::
diff --git a/site/docs/examples/JOIN/0020-aliased-inner-join.mdx b/site/docs/examples/JOIN/0020-aliased-inner-join.mdx
@@ -15,4 +15,18 @@ import {
   aliasedInnerJoin
 } from './0020-aliased-inner-join'
 
-<Playground code={aliasedInnerJoin} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={aliasedInnerJoin} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [innerJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#innerJoin)
+ - [leftJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#leftJoin)
+ - [rightJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#rightJoin)
+ - [fullJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#fullJoin)
+:::
diff --git a/site/docs/examples/JOIN/0030-complex-join.mdx b/site/docs/examples/JOIN/0030-complex-join.mdx
@@ -21,4 +21,18 @@ import {
   complexJoin
 } from './0030-complex-join'
 
-<Playground code={complexJoin} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={complexJoin} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [innerJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#innerJoin)
+ - [leftJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#leftJoin)
+ - [rightJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#rightJoin)
+ - [fullJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#fullJoin)
+:::
diff --git a/site/docs/examples/JOIN/0040-subquery-join.mdx b/site/docs/examples/JOIN/0040-subquery-join.mdx
@@ -15,4 +15,18 @@ import {
   subqueryJoin
 } from './0040-subquery-join'
 
-<Playground code={subqueryJoin} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={subqueryJoin} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [innerJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#innerJoin)
+ - [leftJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#leftJoin)
+ - [rightJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#rightJoin)
+ - [fullJoin method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#fullJoin)
+:::
diff --git a/site/docs/examples/JOIN/_category_.json b/site/docs/examples/JOIN/_category_.json
@@ -1,5 +1,5 @@
 {
-  "label": "JOIN",
+  "label": "Join",
   "position": 3,
   "link": {
     "type": "generated-index",

diff --git a/site/docs/examples/SELECT/0010-a-single-column.mdx b/site/docs/examples/SELECT/0010-a-single-column.mdx
@@ -15,4 +15,17 @@ import {
   aSingleColumn
 } from './0010-a-single-column'
 
-<Playground code={aSingleColumn} setupCode={exampleSetup} />
+<div style={{ marginBottom: '1em' }}>
+  <Playground code={aSingleColumn} setupCode={exampleSetup} />
+</div>
+
+:::info More examples
+The API documentation is packed with examples. The API docs are hosted [here](https://kysely-org.github.io/kysely/)
+but you can access the same documentation by hovering over functions/methods/classes in your IDE. The examples are always
+just one hover away!
+
+For example, check out these sections:
+ - [select method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#select)
+ - [selectAll method](https://kysely-org.github.io/kysely/classes/SelectQueryBuilder.html#selectAll)
+ - [selectFrom method](https://kysely-org.github.io/kysely/classes/Kysely.html#selectFrom)
+:::