docs: add vercel build (#3290)

docs/.gitignore

@@ -1,2 +1,3 @@
 site/
 docs/cloud/reference/sdk/js_ts_sdk_ref.md
+.vercel

docs/Makefile

@@ -0,0 +1,47 @@
+.PHONY: lint-docs format-docs build-docs serve-docs serve-clean-docs clean-docs codespell build-typedoc
+
+build-typedoc:
+	cd ../libs/sdk-js && yarn install --include-dev && yarn typedoc
+	cd ../libs/sdk-js && yarn --silent concat-md --decrease-title-levels --ignore=js_ts_sdk_ref.md --start-title-level-at 2 docs > ../../docs/docs/cloud/reference/sdk/js_ts_sdk_ref.md 2>/dev/null
+	#  Add links to the monorepo
+	sed -e '1,10s|@langchain/langgraph-sdk|[@langchain/langgraph-sdk](https://github.com/langchain-ai/langgraph/tree/main/libs/sdk-js)|g' docs/cloud/reference/sdk/js_ts_sdk_ref.md > temp_file && mv temp_file docs/cloud/reference/sdk/js_ts_sdk_ref.md
+
+build-docs: build-typedoc
+	poetry run python -m mkdocs build --clean -f mkdocs.yml --strict
+
+install-vercel-deps:
+	curl -sSL https://install.python-poetry.org | python3 -
+	poetry self update 1.8.5
+
+vercel-build-docs: install-vercel-deps
+	poetry install
+	make build-docs
+
+serve-clean-docs: clean-docs
+	poetry run python -m mkdocs serve -c -f mkdocs.yml --strict -w ../libs/langgraph
+
+serve-docs: build-typedoc
+	poetry run python -m mkdocs serve -f mkdocs.yml -w ../libs/langgraph  -w ../libs/checkpoint -w ../libs/sdk-py --dirty
+
+clean-docs:
+	find ./docs -name "*.ipynb" -type f -delete
+	rm -rf site
+
+## Run format against the project documentation.
+format-docs:
+	poetry run ruff format docs
+	poetry run ruff check --fix docs
+
+# Check the docs for linting violations
+lint-docs:
+	poetry run ruff format --check docs
+	poetry run ruff check docs
+
+codespell:
+	./codespell_notebooks.sh .
+
+start-services:
+	docker compose -f test-compose.yml up -V --force-recreate --wait --remove-orphans
+
+stop-services:
+	docker compose -f test-compose.yml down

docs/README.md

@@ -19,23 +19,21 @@ make serve-docs
 If you would like to automatically execute all of the notebooks, to mimic the "Run notebooks" GHA, you can run:
 
 ```bash
-python docs/_scripts/prepare_notebooks_for_ci.py
-./docs/_scripts/execute_notebooks.sh
+python _scripts/prepare_notebooks_for_ci.py
+./_scripts/execute_notebooks.sh
 ```
 
 **Note**: if you want to run the notebooks without `%pip install` cells, you can run:
 
 ```bash
-python docs/_scripts/prepare_notebooks_for_ci.py --comment-install-cells
-./docs/_scripts/execute_notebooks.sh
+python _scripts/prepare_notebooks_for_ci.py --comment-install-cells
+./_scripts/execute_notebooks.sh
 ```
 
 `prepare_notebooks_for_ci.py` script will add VCR cassette context manager for each cell in the notebook, so that:
 * when the notebook is run for the first time, cells with network requests will be recorded to a VCR cassette file
 * when the notebook is run subsequently, the cells with network requests will be replayed from the cassettes
 
-**Note**: this is currently limited only to the notebooks in `docs/docs/how-tos`
-
 ## Adding new notebooks
 
 If you are adding a notebook with API requests, it's **recommended** to record network requests so that they can be subsequently replayed. If this is not done, the notebook runner will make API requests every time the notebook is run, which can be costly and slow.
@@ -48,14 +46,14 @@ Then, run
 jupyter execute <path_to_notebook>
 ```
 
-Once the notebook is executed, you should see the new VCR cassettes recorded in `docs/cassettes` directory and discard the updated notebook.
+Once the notebook is executed, you should see the new VCR cassettes recorded in `cassettes` directory and discard the updated notebook.
 
 ## Updating existing notebooks
 
-If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook in `docs/cassettes` directory (each cassette is prefixed with the notebook name), and then run the steps from the "Adding new notebooks" section above.
+If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook in `cassettes` directory (each cassette is prefixed with the notebook name), and then run the steps from the "Adding new notebooks" section above.
 
 To delete cassettes for a notebook, you can run:
 
 ```bash
-rm docs/cassettes/<notebook_name>*
+rm cassettes/<notebook_name>*
 ```

docs/_scripts/execute_notebooks.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Read the list of notebooks to skip from the JSON file
-SKIP_NOTEBOOKS=$(python -c "import json; print('\n'.join(json.load(open('docs/notebooks_no_execution.json'))))")
+SKIP_NOTEBOOKS=$(python -c "import json; print('\n'.join(json.load(open('notebooks_no_execution.json'))))")
 
 # Function to execute a single notebook
 execute_notebook() {
@@ -27,7 +27,7 @@ if [ $# -gt 0 ]; then
     notebooks=$(echo "$@" | tr ' ' '\n' | grep -vFf <(echo "$SKIP_NOTEBOOKS"))
 else
     # Find all notebooks and filter out those in the skip list
-    notebooks=$(find docs/docs/tutorials docs/docs/how-tos -name "*.ipynb" | grep -v ".ipynb_checkpoints" | grep -vFf <(echo "$SKIP_NOTEBOOKS"))
+    notebooks=$(find docs/tutorials docs/how-tos -name "*.ipynb" | grep -v ".ipynb_checkpoints" | grep -vFf <(echo "$SKIP_NOTEBOOKS"))
 fi
 
 # Execute notebooks sequentially

docs/_scripts/prepare_notebooks_for_ci.py

@@ -7,7 +7,7 @@ import click
 import nbformat
 
 logger = logging.getLogger(__name__)
-NOTEBOOK_DIRS = ("docs/docs/how-tos","docs/docs/tutorials")
+NOTEBOOK_DIRS = ("docs/how-tos","docs/tutorials")
 DOCS_PATH = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 CASSETTES_PATH = os.path.join(DOCS_PATH, "cassettes")
 
@@ -19,37 +19,37 @@ BLOCKLIST_COMMANDS = (
 )
 
 NOTEBOOKS_NO_CASSETTES = (
-    "docs/docs/how-tos/visualization.ipynb",
-    "docs/docs/how-tos/many-tools.ipynb"
+    "docs/how-tos/visualization.ipynb",
+    "docs/how-tos/many-tools.ipynb"
 )
 
 NOTEBOOKS_NO_EXECUTION = [
     # this uses a user provided project name for langsmith
-    "docs/docs/tutorials/tnt-llm/tnt-llm.ipynb",
+    "docs/tutorials/tnt-llm/tnt-llm.ipynb",
     # this uses langsmith datasets
-    "docs/docs/tutorials/chatbot-simulation-evaluation/langsmith-agent-simulation-evaluation.ipynb",
+    "docs/tutorials/chatbot-simulation-evaluation/langsmith-agent-simulation-evaluation.ipynb",
     # this uses browser APIs
-    "docs/docs/tutorials/web-navigation/web_voyager.ipynb",
+    "docs/tutorials/web-navigation/web_voyager.ipynb",
     # these RAG guides use an ollama model
-    "docs/docs/tutorials/rag/langgraph_adaptive_rag_local.ipynb",
-    "docs/docs/tutorials/rag/langgraph_crag_local.ipynb",
-    "docs/docs/tutorials/rag/langgraph_self_rag_local.ipynb",
+    "docs/tutorials/rag/langgraph_adaptive_rag_local.ipynb",
+    "docs/tutorials/rag/langgraph_crag_local.ipynb",
+    "docs/tutorials/rag/langgraph_self_rag_local.ipynb",
     # this loads a massive dataset from gcp
-    "docs/docs/tutorials/usaco/usaco.ipynb",
+    "docs/tutorials/usaco/usaco.ipynb",
     # TODO: figure out why autogen notebook is not runnable (they are just hanging. possible due to code execution?)
-    "docs/docs/how-tos/autogen-integration.ipynb",
-    "docs/docs/how-tos/autogen-integration-functional.ipynb",
+    "docs/how-tos/autogen-integration.ipynb",
+    "docs/how-tos/autogen-integration-functional.ipynb",
     # TODO: need to update these notebooks to make sure they are runnable in CI
-    "docs/docs/tutorials/storm/storm.ipynb",  # issues only when running with VCR
-    "docs/docs/tutorials/lats/lats.ipynb",  # issues only when running with VCR
-    "docs/docs/tutorials/rag/langgraph_crag.ipynb",  # flakiness from tavily
-    "docs/docs/tutorials/rag/langgraph_adaptive_rag.ipynb",  # flakiness only when running in GHA 
-    "docs/docs/tutorials/rag/langgraph_self_rag.ipynb",  # flakiness only when running in GHA
-    "docs/docs/tutorials/rag/langgraph_agentic_rag.ipynb",  # flakiness only when running in GHA
-    "docs/docs/how-tos/map-reduce.ipynb",  # flakiness from structured output, only when running with VCR
-    "docs/docs/tutorials/tot/tot.ipynb",
-    "docs/docs/how-tos/visualization.ipynb",
-    "docs/docs/tutorials/llm-compiler/LLMCompiler.ipynb"
+    "docs/tutorials/storm/storm.ipynb",  # issues only when running with VCR
+    "docs/tutorials/lats/lats.ipynb",  # issues only when running with VCR
+    "docs/tutorials/rag/langgraph_crag.ipynb",  # flakiness from tavily
+    "docs/tutorials/rag/langgraph_adaptive_rag.ipynb",  # flakiness only when running in GHA 
+    "docs/tutorials/rag/langgraph_self_rag.ipynb",  # flakiness only when running in GHA
+    "docs/tutorials/rag/langgraph_agentic_rag.ipynb",  # flakiness only when running in GHA
+    "docs/how-tos/map-reduce.ipynb",  # flakiness from structured output, only when running with VCR
+    "docs/tutorials/tot/tot.ipynb",
+    "docs/how-tos/visualization.ipynb",
+    "docs/tutorials/llm-compiler/LLMCompiler.ipynb"
 ]
 
 
@@ -217,7 +217,7 @@ def process_notebooks(should_comment_install_cells: bool) -> None:
                 except Exception as e:
                     logger.error(f"Error processing {notebook_path}: {e}")
     
-    with open(os.path.join(DOCS_PATH, "notebooks_no_execution.json"), "w") as f:
+    with open("notebooks_no_execution.json", "w") as f:
         json.dump(NOTEBOOKS_NO_EXECUTION, f)
 
 

docs/docs/how-tos/agent-handoffs.ipynb

@@ -83,18 +83,10 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "b4864843-00a1-4c88-9a7c-c34e6c31c548",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "ANTHROPIC_API_KEY:  ········\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "import getpass\n",
     "import os\n",

docs/docs/index.md

@@ -3,4 +3,4 @@ hide_comments: true
 title: Home
 ---
 
-{!README.md!}
+{!../README.md!}

docs/docs/tutorials/introduction.ipynb

@@ -35,18 +35,10 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "705d4020-6ee8-44cc-b1a5-8c34e7172fc7",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "ANTHROPIC_API_KEY:  ········\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "import getpass\n",
     "import os\n",
@@ -2472,7 +2464,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

docs/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "docs",
+  "version": "1.0.0",
+  "license": "MIT",
+  "scripts": {
+    "build": "echo 'export PATH=$PATH:/vercel/.local/bin:$PATH' > ~/.bashrc && source ~/.bashrc && make vercel-build-docs"
+  }
+}

docs/pyproject.toml

@@ -0,0 +1,79 @@
+[tool.poetry]
+name = "langgraph-monorepo"
+version = "0.0.1"
+description = "LangGraph monorepo"
+authors = []
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+aiohappyeyeballs = "2.4.3"
+
+[tool.poetry.group.docs.dependencies]
+langgraph = { path = "../libs/langgraph/", develop = true }
+langgraph-checkpoint = { path = "../libs/checkpoint/", develop = true }
+langgraph-checkpoint-sqlite = { path = "../libs/checkpoint-sqlite", develop = true }
+langgraph-checkpoint-postgres = { path = "../libs/checkpoint-postgres", develop = true }
+langgraph-sdk = {path = "../libs/sdk-py", develop = true}
+mkdocs = "^1.6.0"
+mkdocs-autorefs = ">=1.0.1,<1.1.0"
+mkdocstrings = "^0.25.1"
+mkdocstrings-python = "^1.10.4"
+mkdocs-minify-plugin = "^0.8.0"
+mkdocs-rss-plugin = "^1.13.1"
+mkdocs-git-committers-plugin-2 = "^2.3.0"
+mkdocs-material = {extras = ["imaging"], version = "^9.5.27"}
+markdown-include = "^0.8.1"
+markdown-callouts = "^0.4.0"
+mkdocs-exclude = "^1.0.2"
+vcrpy = "^6.0.1"
+click = "^8.1.7"
+ruff = "^0.6.8"
+jupyter = "^1.1.1"
+
+[tool.poetry.group.test.dependencies]
+langchain = "^0.3.8"
+langchain-openai = "^0.3.0"
+langchain-anthropic = "^0.2.1"
+langchain-nomic = "^0.1.3"
+langchain-fireworks = "^0.2.0"
+langchain-community = "^0.3.0"
+langchain-experimental = "^0.3.2"
+langgraph-checkpoint-mongodb = "^0.1.0"
+langsmith = "^0.2.0"
+chromadb = "^0.5.5"
+gpt4all = "^2.8.2"
+scikit-learn = "^1.5.2"
+numexpr = "^2.10.1"
+numpy = "^1.26.4"
+matplotlib = "^3.9.2"
+redis = "^5.0.8"
+pymongo = "^4.8.0"
+motor = "^3.5.1"
+grandalf = "^0.8"
+pyppeteer = "^2.0.0"
+networkx = "^3.3"
+autogen = { version = "^0.3.0", python = "<3.13,>=3.8" }
+
+[tool.poetry.group.test]
+optional = true
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.ruff]
+extend-include = ["*.ipynb"]
+
+[tool.ruff.lint.per-file-ignores]
+"docs/*" = [
+    "E402", # allow imports to appear anywhere in docs
+    "F401", # allow "imported but unused" example code
+    "F811", # allow re-importing the same module, so that cells can stay independent
+    "F841", # allow assignments to variables that are never read -- it's example code
+    # The issues below should be cleaned up when there's time
+    "E722", # allow base imports in notebooks
+]
+

docs/vercel.json

@@ -0,0 +1,4 @@
+{
+  "buildCommand": "yarn build",
+  "outputDirectory": "site"
+}