Generate api refs with typedoc (#3152)

* Generate api refs with typedoc

* update langchain build script

* wrap api site with nextjs site and gitignore any auto gen docs

* update gitignore

* del file

* update scripts

* nit

* improved script

* remove api gen from docusaurus

* omit readme from api docs gen

* conditonal api docs build

* gh action only runs on PR not push

* update

* set shell to bash and update readme

* another updaye

* stop escaping double quote

* use shell script for conditional check

* remove deploy preview

* fix api ref links and codeblock link gen. also added api to header external link

* refactor code, slight cleanup

* fix: update docs build

* chore: lint files

* del gh actions for api docs

* added script for adding ignore to all classes

* better

* ignore abstract

* dont ignore abstract

* cleanup

* account for single line jsdoc

* cr

* nit

* cr

* nits

* cr

* cr

* fixed

* cr

* add api docs redirects

* cr

* chore: lint files

* cr

* build api refs on core docs start

* fix api refs staart

* set port to 3001

* only log on error typedoc

* Update .gitignore

---------

Co-authored-by: jacoblee93 <[email protected]>

.github/workflows/test-exports.yml

@@ -1,8 +1,8 @@
 name: Environment tests
 
 on:
-  workflow_dispatch:  # Allows triggering the workflow manually in GitHub UI
-  workflow_call:  # Allows triggering the workflow from another workflow
+  workflow_dispatch: # Allows triggering the workflow manually in GitHub UI
+  workflow_call: # Allows triggering the workflow from another workflow
 
 # If another push to the same PR or branch happens while this workflow is still running,
 # cancel the earlier run in favor of the next run.
@@ -35,6 +35,9 @@ jobs:
         run: yarn install --immutable
       - name: Build
         run: yarn workspace langchain build
+        shell: bash
+        env:
+          SKIP_API_DOCS: true
 
       - name: Test esbuild exports
         run: docker compose -f docker-compose.yml run test-exports-esbuild
@@ -52,6 +55,9 @@ jobs:
         run: yarn install --immutable
       - name: Build
         run: yarn workspace langchain build
+        shell: bash
+        env:
+          SKIP_API_DOCS: true
 
       - name: Test esm exports
         run: docker compose -f docker-compose.yml run test-exports-esm
@@ -69,6 +75,9 @@ jobs:
         run: yarn install --immutable
       - name: Build
         run: yarn workspace langchain build
+        shell: bash
+        env:
+          SKIP_API_DOCS: true
 
       - name: Test cjs exports
         run: docker compose -f docker-compose.yml run test-exports-cjs
@@ -86,6 +95,9 @@ jobs:
         run: yarn install --immutable
       - name: Build
         run: yarn workspace langchain build
+        shell: bash
+        env:
+          SKIP_API_DOCS: true
 
       - name: Test cf exports
         run: docker compose -f docker-compose.yml run test-exports-cf
@@ -103,6 +115,9 @@ jobs:
         run: yarn install --immutable
       - name: Build
         run: yarn workspace langchain build
+        shell: bash
+        env:
+          SKIP_API_DOCS: true
 
       - name: Test vercel exports
         run: docker compose -f docker-compose.yml run test-exports-vercel
@@ -120,6 +135,9 @@ jobs:
         run: yarn install --immutable
       - name: Build
         run: yarn workspace langchain build
+        shell: bash
+        env:
+          SKIP_API_DOCS: true
 
       - name: Test vite exports
         run: docker compose -f docker-compose.yml run test-exports-vite
@@ -137,6 +155,9 @@ jobs:
         run: yarn install --immutable
       - name: Build
         run: yarn workspace langchain build
+        shell: bash
+        env:
+          SKIP_API_DOCS: true
 
       - name: Test bun exports
         run: docker compose -f docker-compose.yml run test-exports-bun

.gitignore

@@ -36,4 +36,9 @@ firestore-debug.log
 tmp/
 
 **/convex/.gitignore
-**/convex/tsconfig.json
+**/convex/tsconfig.json
+
+langchain/api_refs_docs_build/dist/**/*
+
+.docusaurus/
+docs/build/

docs/api_refs/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "next/core-web-vitals"
+}

docs/api_refs/.gitignore

@@ -0,0 +1,39 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# Autogenerated docs
+/public/*

docs/api_refs/README.md

@@ -0,0 +1,11 @@
+# Auto-generated API documentation for LangChainJS
+
+Do not edit the contents of this directory directly.
+
+## Usage
+
+To build the API refs run `yarn build` from the root of this directory, then `yarn dev` or `yarn start` to serve the docs locally.
+This app uses [Typedoc](https://typedoc.org/) to generate API references from the source code. The generated HTML is then placed inside the `/public` directory, which is served by [Next.js](https://nextjs.org/).
+There is a default redirect when requests are made to `/` which redirects to `/index.html`.
+
+The API references are gitignored by default, so they will not be committed to the repo.

docs/api_refs/generate_typedoc.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+BASE_DIR="../../langchain"
+
+# Create a directory to temp hold the files in src
+# `api_refs_docs_build` is gitignored by default.
+mkdir -p "$BASE_DIR/api_refs_docs_build/dist"
+
+# Copy the contents of src to docs/dist
+cp -r "$BASE_DIR/src/." "$BASE_DIR/api_refs_docs_build/dist/"
+
+# This command will add `@ignore` to JSDoc comments
+# for properties which should be ignored.
+yarn add-ignore-comments
+
+# This command will generate the docs
+yarn typedoc
+
+# Remove the current contents of langchain/src
+rm -rf "$BASE_DIR/api_refs_docs_build/*"
+
+# Copy the unedited contents from docs/dist to langchain/src
+cp -r "$BASE_DIR/api_refs_docs_build/dist/." "$BASE_DIR/src/"

docs/api_refs/next.config.js

@@ -0,0 +1,14 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  async redirects() {
+    return [
+      {
+        source: '/',
+        destination: '/index.html',
+        permanent: false,
+      },
+    ]
+  },
+}
+
+module.exports = nextConfig

docs/api_refs/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "api_refs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "typedoc": "npx typedoc --options typedoc.json",
+    "build:typedoc": "bash ./generate_typedoc.sh",
+    "add-ignore-comments": "cd ../../langchain && node scripts/build-for-api-ref-docs.js",
+    "build": "yarn build:typedoc && next build",
+    "start": "yarn build && next start -p 3001",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "14.0.1",
+    "react": "^18",
+    "react-dom": "^18"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "autoprefixer": "^10.0.1",
+    "eslint": "^8",
+    "eslint-config-next": "14.0.1",
+    "postcss": "^8",
+    "tailwindcss": "^3.3.0",
+    "typescript": "^5"
+  }
+}

docs/api_refs/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

docs/api_refs/tailwind.config.ts

@@ -0,0 +1,20 @@
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  content: [
+    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
+    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
+    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+  theme: {
+    extend: {
+      backgroundImage: {
+        'gradient-radial': 'radial-gradient(var(--tw-gradient-stops))',
+        'gradient-conic':
+          'conic-gradient(from 180deg at 50% 50%, var(--tw-gradient-stops))',
+      },
+    },
+  },
+  plugins: [],
+}
+export default config

docs/api_refs/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}