refactor: autogen graphql docs

Author: PaulRBerg

biome.jsonc

@@ -2,6 +2,12 @@
   "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "extends": ["@sablier/devkit/biome"],
   "files": {
-    "includes": ["**/*.{css,js,json,jsonc,jsx,ts,tsx}", "!node_modules", "!repos", "!src/autogen", "!static"]
+    "includes": [
+      "**/*.{css,js,json,jsonc,jsx,ts,tsx}",
+      "!node_modules/**",
+      "!repos/**",
+      "!src/autogen/**",
+      "!static/**"
+    ]
   }
 }

bun.lock

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import { join } from "node:path";
+import { getSablierIndexerEnvio, type Indexer } from "@sablier/indexers";
+import { Command } from "commander";
+import { $ } from "execa";
+import * as yaml from "js-yaml";
+import _ from "lodash";
+import type { CliOptions } from "../../types";
+
+const CHAIN_ID_SEPOLIA = 11155111;
+
+type Category = {
+  /** @see https://docusaurus.io/feature-requests/p/hiding-parts-of-docs-in-autogenerated-sidebar */
+  className?: "hidden";
+  collapsible: boolean;
+  collapsed: boolean;
+  label: string;
+  position: number;
+};
+
+type GraphQLOptions = CliOptions & {
+  protocol: string;
+  vendor: string;
+};
+
+/* -------------------------------------------------------------------------- */
+/*                                   COMMAND                                  */
+/* -------------------------------------------------------------------------- */
+
+export function createGraphQLCommand(): Command {
+  return new Command("graphql")
+    .description("Generate GraphQL schema documentation")
+    .requiredOption("-p, --protocol <protocol>", "generate for specific protocol")
+    .requiredOption("-v, --vendor <vendor>", "generate for specific vendor")
+    .action(async (options, command: Command) => {
+      const globalOptions = command.parent?.opts() || {};
+      const mergedOptions: GraphQLOptions = { ...globalOptions, ...options };
+      await generateGraphQL(mergedOptions);
+    });
+}
+
+export async function generateGraphQL(options: GraphQLOptions): Promise<void> {
+  const protocols: Indexer.Protocol[] = ["airdrops", "flow", "lockup"];
+  const vendors = ["graph", "envio"];
+
+  if (options.protocol !== "all" && !protocols.includes(options.protocol as Indexer.Protocol)) {
+    throw new Error(`Invalid protocol: ${options.protocol}. Valid options: ${protocols.join(", ")}, all`);
+  }
+  if (options.vendor !== "all" && !vendors.includes(options.vendor as Indexer.Vendor)) {
+    throw new Error(`Invalid vendor: ${options.vendor}. Valid options: ${vendors.join(", ")}, all`);
+  }
+
+  let targetProtocols = protocols;
+  if (options.protocol !== "all") {
+    targetProtocols = _.filter(protocols, (p) => p === options.protocol);
+  }
+
+  const basePaths: string[] = [];
+  for (const p of targetProtocols) {
+    if (options.vendor === "all" || options.vendor === "graph") {
+      basePaths.push(await generateGraph(p));
+    }
+    if (options.vendor === "all" || options.vendor === "envio") {
+      basePaths.push(await generateEnvio(p));
+    }
+  }
+
+  cleanupDocs(basePaths);
+}
+
+/* -------------------------------------------------------------------------- */
+/*                               INTERNAL LOGIC                               */
+/* -------------------------------------------------------------------------- */
+
+const COLLAPSED = {
+  collapsed: true,
+  collapsible: true,
+};
+
+const THE_GRAPH_CATEGORY: Category = { ...COLLAPSED, label: "The Graph", position: 2 };
+const ENVIO_CATEGORY: Category = { ...COLLAPSED, label: "Envio", position: 3 };
+const QUERIES_CATEGORY: Category = { ...COLLAPSED, label: "Queries", position: 2 }; // first is the overview
+const OBJECTS_CATEGORY: Category = { ...COLLAPSED, label: "Objects", position: 3 };
+const ENUMS_CATEGORY: Category = { ...COLLAPSED, className: "hidden", label: "Enums", position: 4 };
+const INPUTS_CATEGORY: Category = { ...COLLAPSED, className: "hidden", label: "Inputs", position: 5 };
+const SCALARS_CATEGORY: Category = { ...COLLAPSED, className: "hidden", label: "Scalars", position: 6 };
+
+function cleanupDocs(basePaths: string[]): void {
+  for (const basePath of basePaths) {
+    fs.rmSync(join(basePath, "directives"), { force: true, recursive: true });
+    fs.rmSync(join(basePath, "subscriptions"), { force: true, recursive: true });
+
+    // Delete all _category_.yml files
+    fs.unlinkSync(join(basePath, "queries", "_category_.yml"));
+    fs.unlinkSync(join(basePath, "enums", "_category_.yml"));
+    fs.unlinkSync(join(basePath, "inputs", "_category_.yml"));
+    fs.unlinkSync(join(basePath, "objects", "_category_.yml"));
+    fs.unlinkSync(join(basePath, "scalars", "_category_.yml"));
+
+    // Rewrite _category_.yml files
+    fs.writeFileSync(join(basePath, "queries", "_category_.yml"), yaml.dump(QUERIES_CATEGORY));
+    fs.writeFileSync(join(basePath, "objects", "_category_.yml"), yaml.dump(OBJECTS_CATEGORY));
+    fs.writeFileSync(join(basePath, "enums", "_category_.yml"), yaml.dump(ENUMS_CATEGORY));
+    fs.writeFileSync(join(basePath, "inputs", "_category_.yml"), yaml.dump(INPUTS_CATEGORY));
+    fs.writeFileSync(join(basePath, "scalars", "_category_.yml"), yaml.dump(SCALARS_CATEGORY));
+
+    // Write vendor category file at base path
+    if (basePath.includes("envio")) {
+      fs.writeFileSync(join(basePath, "_category_.yml"), yaml.dump(ENVIO_CATEGORY));
+    } else if (basePath.includes("the-graph")) {
+      fs.writeFileSync(join(basePath, "_category_.yml"), yaml.dump(THE_GRAPH_CATEGORY));
+    }
+  }
+}
+
+async function generateEnvio(protocol: Indexer.Protocol): Promise<string> {
+  const base = `./docs/api/${protocol}/graphql/envio`;
+  const schemaURL = getSablierIndexerEnvio({ chainId: CHAIN_ID_SEPOLIA, protocol }).endpoint.url;
+
+  await runCommand(base, schemaURL);
+  console.log(`✔️ Generated GraphQL docs for Envio vendor and ${_.capitalize(protocol)} protocol\n`);
+  return base;
+}
+
+async function generateGraph(protocol: Indexer.Protocol): Promise<string> {
+  const base = `./docs/api/${protocol}/graphql/the-graph`;
+  const schemaURL = `https://api.studio.thegraph.com/query/112500/sablier-${protocol}-experimental/version/latest`;
+
+  await runCommand(base, schemaURL);
+  console.log(`✔️ Generated GraphQL docs for The Graph vendor and ${_.capitalize(protocol)} protocol\n`);
+  return base;
+}
+
+/**
+ * @see https://graphql-markdown.dev/docs/settings#baseurl
+ * @see {@link file://./../../../config/plugins.ts}
+ */
+async function runCommand(base: string, schema: string): Promise<void> {
+  await $({ stdio: "inherit" })`bun docusaurus graphql-to-doc --base ${base} --schema ${schema}`;
+}

cli/commands/autogen/graphql.ts

@@ -12,10 +12,11 @@ async function main() {
   // Import and create subcommands
   const { createDeploymentsCommand, generateDeployments } = await import("./commands/autogen/deployments.js");
   const { createIndexersCommand, generateIndexers } = await import("./commands/autogen/indexers.js");
+  const { createGraphQLCommand } = await import("./commands/autogen/graphql.js");
 
   // Create autogen parent command
   const autogenCommand = new Command("autogen")
-    .description("Auto-generate documentation tables")
+    .description("Auto-generate documentation and indexers tables")
     .action(async (_options, command) => {
       const globalOptions = command.parent?.opts() || {};
 
@@ -36,6 +37,7 @@ async function main() {
   // Add subcommands to autogen
   autogenCommand.addCommand(createDeploymentsCommand());
   autogenCommand.addCommand(createIndexersCommand());
+  autogenCommand.addCommand(createGraphQLCommand());
 
   // Add the autogen command to the main program
   program.addCommand(autogenCommand);

cli/index.ts

@@ -1,8 +1,13 @@
 import type { Options as ClientRedirectsOptions } from "@docusaurus/plugin-client-redirects";
 import type { Options as VercelAnalyticsOptions } from "@docusaurus/plugin-vercel-analytics";
-import { type DocusaurusConfig } from "@docusaurus/types";
+import { type DocusaurusConfig, type PluginOptions } from "@docusaurus/types";
+import type { ConfigOptions, GraphQLMarkdownCliOptions, LoaderOption } from "@graphql-markdown/types";
 import { createRedirects, redirects } from "./redirects";
 
+/* -------------------------------------------------------------------------- */
+/*                              Client Redirects                              */
+/* -------------------------------------------------------------------------- */
+
 const clientRedirects: [string, ClientRedirectsOptions] = [
   "@docusaurus/plugin-client-redirects",
   {
@@ -12,11 +17,45 @@ const clientRedirects: [string, ClientRedirectsOptions] = [
   },
 ];
 
+/* -------------------------------------------------------------------------- */
+/*                              GraphQL Markdown                              */
+/* -------------------------------------------------------------------------- */
+type GraphQLMarkdownOptions = GraphQLMarkdownCliOptions & Partial<PluginOptions>;
+
+const graphqlMarkdown: [string, GraphQLMarkdownOptions] = [
+  "@graphql-markdown/docusaurus",
+  /**
+   * Some settings will be overridden by the CLI.
+   * @see https://graphql-markdown.dev/docs/settings
+   */
+  {
+    baseURL: "./docs/api/flow/the-graph",
+    homepage: "static/graphql-overview.md",
+    loaders: {
+      UrlLoader: {
+        module: "@graphql-tools/url-loader",
+      },
+    } as LoaderOption,
+    metatags: [{ content: "noindex", name: "robots" }, { charset: "utf-8" }],
+    pretty: true,
+    printTypeOptions: {
+      hierarchy: "entity",
+      relatedTypeSection: false,
+    },
+    rootPath: ".",
+    schema: "https://api.studio.thegraph.com/query/112500/sablier-flow-experimental/version/latest",
+  } satisfies ConfigOptions,
+];
+
+/* -------------------------------------------------------------------------- */
+/*                              VERCEL ANALYTICS                              */
+/* -------------------------------------------------------------------------- */
+
 const vercelAnalytics: [string, VercelAnalyticsOptions] = [
   "vercel-analytics",
   {
     mode: "auto",
   },
 ];
 
-export const plugins: DocusaurusConfig["plugins"] = [clientRedirects, vercelAnalytics];
+export const plugins: DocusaurusConfig["plugins"] = [clientRedirects, graphqlMarkdown, vercelAnalytics];