docs: improve docs and auto generate config docs (#56)

* docs: document class consolidation

* auto generate configuration docs

Author: danadajian

.github/workflows/docs.yml

@@ -18,10 +18,6 @@ concurrency:
   group: pages
   cancel-in-progress: false
 
-defaults:
-  run:
-    working-directory: docs
-
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -35,8 +31,16 @@ jobs:
       - name: Install Dependencies
         run: bun install
 
+      - name: Build Plugin
+        run: bun run build
+
+      - name: Install Docs Dependencies
+        run: bun install
+        working-directory: docs
+
       - name: Build Docs
         run: bun docs:build
+        working-directory: docs
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

.prettierignore

@@ -0,0 +1 @@
+*.hbs

docs/.gitignore

@@ -7,6 +7,7 @@
 # Generated files
 .docusaurus
 .cache-loader
+docs/configuration.md
 
 # Misc
 .DS_Store

docs/bun.lockb

@@ -0,0 +1,83 @@
+---
+sidebar_position: 5
+---
+
+# Class Consolidation
+
+In GraphQL, it's common to have input types that mirror output types. For example, you might have a `UserInput` type for creating a user and a `User` type for querying a user. These types might have the same fields but are treated as separate types in GraphQL.
+
+With the class consolidation feature, GraphQL Kotlin Codegen can detect when these types are equivalent and consolidate them into a single Kotlin class.
+If this class functions in your resolver code as both an input and an output type, GraphQL Kotlin will subsequently
+transform it into the separate input and output types we started with.
+
+## How It Works
+
+The class consolidation feature works by comparing the fields of input and output types. If the fields and their types
+are exactly the same, the types are considered equivalent.
+
+Here's an example:
+
+```graphql
+input UserInput {
+  name: String!
+  email: String!
+}
+
+type User {
+  name: String!
+  email: String!
+}
+```
+
+In this case, `UserInput` and `User` have the same fields, so they would be consolidated into a single Kotlin class:
+
+```kotlin
+data class User(
+  val name: String,
+  val email: String
+)
+```
+
+This also works recursively. If the fields of a type are themselves input or output types, they will be consolidated as well.
+
+```graphql
+input UserInput {
+  name: NameInput!
+  email: String!
+}
+
+input NameInput {
+  first: String!
+  last: String!
+}
+
+type User {
+  name: Name!
+  email: String!
+}
+
+type Name {
+  first: String!
+  last: String!
+}
+```
+
+```kotlin
+data class User(
+  val name: Name,
+  val email: String
+)
+
+data class Name(
+  val first: String,
+  val last: String
+)
+```
+
+## Limitations
+
+The class consolidation feature only works with types that have the same fields with the same types.
+If the fields are different, the types will not be consolidated. Instead, individual classes will be generated with the
+`@GraphQLValidObjectLocations` annotation, enforcing that the class can only be used as either an input or output type.
+Check out the [GraphQL Kotlin docs](https://opensource.expediagroup.com/graphql-kotlin/docs/schema-generator/customizing-schemas/restricting-input-output)
+to learn more about this annotation.

docs/docs/class-consolidation.md

@@ -60,7 +60,7 @@ class MyQuery : Query, QueryInterface() {
 
 ```
 
-The resulting source code is at risk of being extremely unperformant. The `MyType` class is a data class, which means
+The resulting source code is extremely unperformant. The `MyType` class is a data class, which means
 that the `field1` and `field2` properties are both initialized when the `MyType` object is created, and
 `myExpensiveCall1()` and `myExpensiveCall2()` will both be called in sequence! Even if I only query for `field1`, not
 only will `myExpensiveCall2()` still run, but it will also wait until `myExpensiveCall1()` is totally finished.

docs/docs/configuration.md

@@ -1,9 +1,8 @@
 import { themes as prismThemes } from "prism-react-renderer";
 import type { Config } from "@docusaurus/types";
 import type * as Preset from "@docusaurus/preset-classic";
-import * as path from "path";
 
-const config: Config = {
+export default {
   title: "GraphQL Kotlin Codegen",
   favicon: "img/favicon.ico",
 
@@ -30,15 +29,6 @@ const config: Config = {
       } satisfies Preset.Options,
     ],
   ],
-  themes: [
-    path.resolve(
-      __dirname,
-      "node_modules",
-      "docusaurus-theme-github-codeblock",
-      "build",
-      "index.js",
-    ),
-  ],
   themeConfig: {
     navbar: {
       title: "GraphQL Kotlin Codegen",
@@ -76,6 +66,4 @@ const config: Config = {
       darkTheme: prismThemes.dracula,
     },
   } satisfies Preset.ThemeConfig,
-};
-
-export default config;
+} satisfies Config;

docs/docs/recommended-usage.md

@@ -0,0 +1,5 @@
+{
+  "source": {
+    "includePattern": ".+\\.(js|cjs|mjs)$"
+  }
+}

docs/docusaurus.config.ts

@@ -3,7 +3,8 @@
   "private": true,
   "scripts": {
     "docs:start": "docusaurus start",
-    "docs:build": "tsc && docusaurus build"
+    "docs:build": "tsc && bun generate && docusaurus build",
+    "generate": "jsdoc2md --files ../dist/plugin.cjs --partial partials/main.hbs --partial partials/scope.hbs -c jsdoc.conf > docs/configuration.md"
   },
   "devDependencies": {
     "@docusaurus/core": "3.2.1",
@@ -13,7 +14,7 @@
     "@docusaurus/types": "3.2.1",
     "@mdx-js/react": "3.0.1",
     "clsx": "2.1.1",
-    "docusaurus-theme-github-codeblock": "2.0.2",
+    "jsdoc-to-markdown": "8.0.1",
     "prism-react-renderer": "2.3.1",
     "react": "18.3.1",
     "react-dom": "18.3.1",