refactor: update and polish API docs

refactor: better organization for static images
refactor: rename AdmonitionSimpleCode to CautionNonProduction
refactor: simplify and polish CLI
refactor: update indexers tables

Author: PaulRBerg

.gitignore

@@ -3,6 +3,7 @@
 .docusaurus
 build
 node_modules
+repomix
 src/autogen/**/*.mdx
 
 # files

CONTRIBUTING.md

@@ -5,58 +5,31 @@ informal concerns or feedback, please join our [Discord server](https://discord.
 
 Contributions to Sablier Docs are welcome by anyone interested in improving readability, or adding new features.
 
-## Pre Requisites
+## Prerequisites
 
-You will need the following software on your machine:
+- [Node.js](https://nodejs.org) (v20+)
+- [Bun](https://bun.sh) (package manager)
 
-- [Git] (https://git-scm.com/downloads)
-- [Node.Js] (https://nodejs.org/en/download/)
-- [Bun] (https://bun.sh/)
+### Setup
 
-### Set Up
-
-Clone this repository:
-
-```shell
-$ git clone [email protected]:sablier-labs/docs.git && cd docs
-```
-
-Then, inside the project's directory, run this to install the Node.js dependencies:
-
-```shell
-$ bun install
-```
-
-Create a new branch and switch to it, this is where all development work should be done:
-
-```shell
-$ git switch <branch-name>
+```bash
+git clone https://github.com/sablier-labs/docs.git sablier-docs
+cd sablier-docs
+bun install
 ```
 
-Now you can start making changes.
-
-Run the following command to starts a local development server and opens up a browser window.
+### Available Commands
 
-```shell
-$ bun run start
+```bash
+bun run                     # Show all available commands
+bun run start               # Build the docs site locally on localhost:3000
+bun run check               # Run all code checks
 ```
 
-To see a list of all available scripts:
-
-```shell
-$ bun run
-```
-
-## Pull Requests
-
-- Before you submit your Pull Request (PR), search the project for an open or closed PR related to your submission to
-  avoid duplicating effort.
-- Make your changes in a new git branch.
-- Commit your changes. Your commit message should follow the
-  [Conventional Commits](https://conventionalcommits.org/en/v1.0.0/) specification
-- Make sure `bun run check` passes.
-- Open a pull request from your forked repository to the original repository.
-
-When making a pull request, ensure that:
+### Development Workflow
 
-- A descriptive summary of the PR has been provided.
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `bun run check` to verify code quality
+5. Submit a pull request

bun.lock

@@ -18,14 +18,15 @@
         "@mdx-js/mdx": "~3.1",
         "@mdx-js/react": "~3.1",
         "@sablier/devkit": "github:sablier-labs/devkit#main",
-        "@sablier/indexers": "1.0.0-alpha.4",
+        "@sablier/indexers": "1.0.0-alpha.6",
         "@vercel/analytics": "^1.5",
         "axios": "^1.9",
         "clsx": "^2.1",
         "docusaurus-plugin-remote-content": "^4.0",
         "docusaurus-theme-github-codeblock": "^2.0",
         "function-plot": "^1.25",
         "hast-util-is-element": "3.0",
+        "lodash": "^4.17",
         "prism-react-renderer": "^2.4",
         "react": "18.2",
         "react-dom": "18.2",
@@ -50,7 +51,6 @@
         "eslint-plugin-react": "^7.37",
         "husky": "^9.1",
         "lint-staged": "^16.1",
-        "lodash": "^4.17",
         "prettier": "^3.5",
         "typescript": "5.8.3",
         "vercel": "^42.3",
@@ -748,7 +748,7 @@
 
     "@sablier/devkit": ["@sablier/devkit@github:sablier-labs/devkit#c12bc44", {}, "sablier-labs-devkit-c12bc44"],
 
-    "@sablier/indexers": ["@sablier/[email protected].4", "", { "dependencies": { "lodash": "^4.17", "sablier": "1.0.0-beta.2" } }, "sha512-bW8vEMpfRPSC5IHAlzpCjqP29W5VfGQFK2FA3HMUs4bTRoVhkyf/P7nhxpkT8buT5P0oGk4J5J4CpuTZ6xFegw=="],
+    "@sablier/indexers": ["@sablier/[email protected].6", "", { "dependencies": { "lodash": "^4.17", "sablier": "1.0.0-beta.2" } }, "sha512-2YpYCyyFJnuTrsPcY+v4CDW+R/e/+qzxzxIFZmNq2wjFA2l5EFBI+bgKSWzd/+P2lgMI2rAjaKe4GhxbGXjKXw=="],
 
     "@scure/base": ["@scure/[email protected]", "", {}, "sha512-8YKhl8GHiNI/pU2VMaofa2Tor7PJRAjwQLBBuilkJ9L5+13yVbC7JO/wS7piioAvPSwR3JKM1IJ/u4xQzbcXKg=="],
 

cli/commands/deployments.ts renamed to cli/commands/autogen/deployments.ts

@@ -1,15 +1,16 @@
 import { Command } from "commander";
+import _ from "lodash";
 import { Protocol, type Sablier, sablier } from "sablier";
-import type { CliOptions } from "../types";
-import { Links } from "../../src/constants";
-import * as helpers from "../helpers";
+import type { CliOptions } from "../../types";
+import { Links } from "../../../src/constants";
+import { autogenFilePaths, getRelative, writeFileWithOverwrite } from "../../helpers";
 
 export function createDeploymentsCommand(): Command {
   return new Command("deployments")
     .description("Generate deployment tables for all Sablier releases")
-    .action(async (_options, command) => {
-      const globalOptions = command.parent?.opts() || {};
-      await generateDeployments(globalOptions);
+    .action(async (_options, command: Command) => {
+      const mergedOptions = command.optsWithGlobals();
+      await generateDeployments(mergedOptions);
     });
 }
 
@@ -24,11 +25,12 @@ export async function generateDeployments(options: CliOptions = {}): Promise<voi
       continue;
     }
 
-    const fileName = helpers.autogenFileNames.deployments(release.version);
-    const filePath = helpers.getAutogenFilePath(release.protocol, fileName);
+    const filePath = autogenFilePaths.deployments(release);
 
-    if (helpers.writeFileWithOverride({ filePath, content: tables, options })) {
-      helpers.log(`✅ Generated table with deployments for ${release.protocol} ${release.version}`, options);
+    if (writeFileWithOverwrite({ filePath, content: tables, options })) {
+      const protocol = _.capitalize(release.protocol);
+      const version = _.capitalize(release.version);
+      console.log(`✔️ Generated deployments table for ${protocol} ${version} at: ${getRelative(filePath)}`);
     }
   }
 }
@@ -47,34 +49,36 @@ function generateTables(release: Sablier.Release) {
   for (const deployment of mainnetDeployments) {
     const chain = sablier.chains.get(deployment.chainId);
     content += `### ${chain.name}\n\n`;
-    content += generateDeploymentTable(deployment, release.protocol, release.version);
+    content += generateDeploymentTable(deployment, release);
     content += "\n";
   }
 
   content += "## Testnets\n\n";
   for (const deployment of testnetDeployments) {
     const chain = sablier.chains.get(deployment.chainId);
     content += `### ${chain.name}\n\n`;
-    content += generateDeploymentTable(deployment, release.protocol, release.version);
+    content += generateDeploymentTable(deployment, release);
     content += "\n";
   }
 
   return content;
 }
 
-function generateDeploymentTable(deployment: Sablier.Deployment, protocol: Sablier.Protocol, version: string): string {
+function generateDeploymentTable(deployment: Sablier.Deployment, release: Sablier.Release): string {
   let table = `| Contract | Address | Deployment |\n`;
   table += `| :-------- | :-------- | :--------- |\n`;
 
   for (const contract of deployment.contracts) {
-    let address: string;
+    let addressCell: string;
     if (contract.explorerURL) {
-      address = `[\`${contract.address}\`](${contract.explorerURL})`;
+      addressCell = `[\`${contract.address}\`](${contract.explorerURL})`;
     } else {
-      address = `\`${contract.address}\``;
+      addressCell = `\`${contract.address}\``;
     }
-    const link = `[\`${protocol}-${version}\`](${Links.GitHub.SDK}/blob/main/deployments/${protocol}/${version})`;
-    table += `| ${contract.name} | ${address} | ${link} |\n`;
+    const protocol = release.protocol;
+    const version = release.version;
+    const linkCell = `[\`${protocol}-${version}\`](${Links.GitHub.SDK}/blob/main/deployments/${protocol}/${version})`;
+    table += `| ${contract.name} | ${addressCell} | ${linkCell} |\n`;
   }
 
   return table;

cli/commands/autogen/indexers.ts

@@ -0,0 +1,80 @@
+import { type Indexer, indexers } from "@sablier/indexers";
+import { Command } from "commander";
+import _ from "lodash";
+import { sablier } from "sablier";
+import type { CliOptions } from "../../types";
+import { autogenFilePaths, getRelative, writeFileWithOverwrite } from "../../helpers";
+
+export function createIndexersCommand(): Command {
+  return new Command("indexers")
+    .description("Generate indexer endpoint tables for all Sablier protocols")
+    .action(async (_options, command: Command) => {
+      const mergedOptions = command.optsWithGlobals();
+      await generateIndexers(mergedOptions);
+    });
+}
+
+export async function generateIndexers(options: CliOptions = {}): Promise<void> {
+  generateTables("airdrops", options);
+  generateTables("flow", options);
+  generateTables("lockup", options);
+}
+
+function generateTables(protocol: Indexer.Protocol, options: CliOptions): void {
+  const graphTable = generateGraphTable(indexers.graph[protocol]);
+  const envioTable = generateEnvioTable(indexers.envio[protocol]);
+
+  const graphFilePath = autogenFilePaths.graph(protocol);
+  if (writeFileWithOverwrite({ filePath: graphFilePath, content: graphTable, options })) {
+    console.log(
+      `✔️  Generated ${_.capitalize(protocol)} endpoints table for The Graph at: ${getRelative(graphFilePath)}`,
+    );
+  }
+
+  const envioFilePath = autogenFilePaths.envio(protocol);
+  if (writeFileWithOverwrite({ filePath: envioFilePath, content: envioTable, options })) {
+    console.log(`✔️  Generated ${_.capitalize(protocol)} endpoints table for Envio at: ${getRelative(envioFilePath)}`);
+  }
+}
+
+function generateGraphTable(indexers: Indexer[]): string {
+  let markdown = `| Chain | Production URL | Testing URL | Explorer URL |\n`;
+  markdown += `| -------- | -------------- | ----------- | ------------ |\n`;
+
+  for (const indexer of indexers) {
+    const chain = sablier.chains.getOrThrow(indexer.chainId);
+
+    const productionURL = indexer.endpoint.url;
+    const testingURL = indexer.playgroundURL;
+    const explorerURL = indexer.explorerURL;
+
+    const productionCell = `[${indexer.name}](${productionURL})`;
+    const testingCell = testingURL ? `[Testing](${testingURL})` : "N/A";
+    const explorerCell = explorerURL ? `[Explorer](${explorerURL})` : "N/A";
+
+    markdown += `| ${chain.name} | ${productionCell} | ${testingCell} | ${explorerCell} |\n`;
+  }
+
+  return markdown;
+}
+
+function generateEnvioTable(indexers: Indexer[]): string {
+  let markdown = `| Chain | Production URL | Testing URL |\n`;
+  markdown += `| -------- | -------------- | ----------- |\n`;
+
+  for (const indexer of indexers) {
+    const chain = sablier.chains.get(indexer.chainId);
+    if (!chain || !chain.name) {
+      continue;
+    }
+
+    const productionURL = indexer.endpoint.url;
+    const testingURL = `https://cloud.hasura.io/public/graphiql?endpoint=${encodeURIComponent(productionURL)}`;
+
+    const productionCell = `${productionURL}`;
+    const testingCell = `[Testing](${testingURL})`;
+    markdown += `| ${chain.name} | ${productionCell} | ${testingCell} |\n`;
+  }
+
+  return markdown;
+}