From 26c68aa528c39af01ec8cf6f2966b65be11d3798 Mon Sep 17 00:00:00 2001 From: Mason Daugherty Date: Thu, 25 Sep 2025 13:31:27 -0400 Subject: [PATCH] docs: update `README` and scripts for improved clarity (#6197) --- docs/README.md | 52 +++++-------------- docs/_scripts/generate_api_reference_links.py | 16 +++++- docs/_scripts/notebook_convert.py | 2 + docs/pyproject.toml | 8 +-- docs/uv.lock | 9 ++-- 5 files changed, 39 insertions(+), 48 deletions(-) diff --git a/docs/README.md b/docs/README.md index 31a2c89c7..ddbef9d0b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,32 +18,36 @@ Main documentation files are located in `docs/docs/` and are written in Markdown ### API Reference -API reference documentation is located in `docs/docs/reference/` and is generated from docstrings in the codebase using the **mkdocstrings** plugin. - -The API reference uses manual directives in markdown files that specify which classes/functions to document: +API reference documentation is defined in `docs/docs/reference/`. Each `.md` file outlines the "template" that each page is built from. Reference content is automatically generated from docstrings in the codebase using the **mkdocstrings** plugin. Once generated, the content is plugged into the corresponding markdown file where it is referenced by using manual directives to specify which classes and/or functions are documented: ```markdown ::: langgraph.graph.state.StateGraph options: + show_if_no_docstring: true + show_root_heading: true + show_root_full_path: false members: - add_node + - add_edge + - add_conditional_edges + - add_sequence - compile ``` -#### Build Process +## Build Process -The build process follows these steps: +Docs are built following these steps: -1. **Content Processing Phase:** +1. **Content Processing:** - `_scripts/notebook_hooks.py` - Main processing pipeline that: - - Converts Jupyter notebooks to markdown using `notebook_convert.py` + - Converts how-tos/tutorial Jupyter notebooks to markdown using `notebook_convert.py` - Adds automatic API reference links to code blocks using `generate_api_reference_links.py` - Handles conditional rendering for Python/JS versions - Processes highlight comments and custom syntax 2. **API Reference Generation:** - **mkdocstrings** plugin extracts docstrings from Python source code - - Manual `::: module.Class` directives in reference pages specify what to document + - Manual `::: module.Class` directives in reference pages (`/docs/docs/*`) specify what to document - Cross-references are automatically generated between docs and API 3. **Site Generation:** @@ -55,7 +59,7 @@ The build process follows these steps: - `make build-docs` generates production build (also usable for local testing) - Automatic redirects handle URL changes between versions -#### Local Development +### Local Development For local development, use the Makefile targets: @@ -76,7 +80,7 @@ The `serve-docs` command: - Includes dirty builds for faster iteration - Serves on [http://127.0.0.1:8000/langgraph/](http://127.0.0.1:8000/langgraph/) -#### Documentation Standards +## Standards **Docstring Format:** The API reference uses **Google-style docstrings** with Markdown markup. The `mkdocstrings` plugin processes these to generate documentation. @@ -114,34 +118,6 @@ def example_function(param1: str, param2: int = 5) -> bool: - **Code blocks**: Standard markdown ``` syntax - **Cross-references**: Automatic linking via `generate_api_reference_links.py` -#### Site Styling and Assets - -**Theme and Styling:** - -- Uses [**Material for MkDocs**](https://squidfunk.github.io/mkdocs-material/) theme -- Custom CSS in `docs/stylesheets/` for LangGraph-specific styling: - - Brand colors and typography - - Custom navigation components - - Version admonitions and agent graph widgets - -**Static Assets:** - -- Logos and favicon in `docs/static/` -- Custom stylesheets in `docs/stylesheets/` - -**Content Processing:** - -- Automatic API reference link generation for code examples -- Jupyter notebook execution with VCR cassettes for reproducible builds -- Conditional rendering for multi-language support -- Extensive redirect mapping for URL stability - -**Analytics and Integration:** - -- Google Tag Manager integration via custom hooks -- GitHub integration (edit buttons, source links) -- Automatic cross-referencing between documentation sections - ## Execute notebooks If you would like to automatically execute all of the notebooks, to mimic the "Run notebooks" GitHub action, you can run: diff --git a/docs/_scripts/generate_api_reference_links.py b/docs/_scripts/generate_api_reference_links.py index 1d65516dd..89d614bd5 100644 --- a/docs/_scripts/generate_api_reference_links.py +++ b/docs/_scripts/generate_api_reference_links.py @@ -1,3 +1,5 @@ +"""Generate API reference links for imports in Python code blocks within markdown files.""" + import ast import importlib import logging @@ -70,8 +72,18 @@ MANUAL_API_REFERENCES_LANGGRAPH = [ ([], "langgraph.checkpoint.postgres.aio", "AsyncPostgresSaver", "checkpoints"), ([], "langgraph.checkpoint.postgres", "PostgresSaver", "checkpoints"), # other prebuilts - (["langgraph_supervisor"], "langgraph_supervisor.supervisor", "create_supervisor", "supervisor"), - (["langgraph_supervisor"], "langgraph_supervisor.handoff", "create_handoff_tool", "supervisor"), + ( + ["langgraph_supervisor"], + "langgraph_supervisor.supervisor", + "create_supervisor", + "supervisor", + ), + ( + ["langgraph_supervisor"], + "langgraph_supervisor.handoff", + "create_handoff_tool", + "supervisor", + ), ([], "langgraph_supervisor.handoff", "create_forward_message_tool", "supervisor"), (["langgraph_swarm"], "langgraph_swarm.swarm", "create_swarm", "swarm"), (["langgraph_swarm"], "langgraph_swarm.swarm", "add_active_agent_router", "swarm"), diff --git a/docs/_scripts/notebook_convert.py b/docs/_scripts/notebook_convert.py index 41c74f194..1ec3fcec5 100644 --- a/docs/_scripts/notebook_convert.py +++ b/docs/_scripts/notebook_convert.py @@ -1,3 +1,5 @@ +"""Convert Jupyter notebooks to markdown with custom processing.""" + import ast import os import re diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 72ef5cd1f..7650912db 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -7,14 +7,14 @@ name = "langgraph-docs" version = "0.0.1" description = "LangGraph docs" authors = [] -requires-python = "~=3.11" +requires-python = ">=3.11.0,<4.0.0" readme = "README.md" license = "MIT" dependencies = [ "aiohappyeyeballs==2.4.3", - "hub>=3.0.1,<4", - "xxhash>=3.5.0,<4", - "black>=25.1.0,<26", + "hub>=3.0.1,<4.0.0", + "xxhash>=3.5.0,<4.0.0", + "black>=25.1.0,<26.0.0", ] [dependency-groups] diff --git a/docs/uv.lock b/docs/uv.lock index 51e596320..000861f33 100644 --- a/docs/uv.lock +++ b/docs/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 2 +revision = 3 requires-python = ">=3.11, <4" resolution-markers = [ "python_full_version >= '3.13' and platform_python_implementation != 'PyPy'", @@ -2337,7 +2337,7 @@ wheels = [ [[package]] name = "langgraph" -version = "0.6.2" +version = "0.6.7" source = { editable = "../libs/langgraph" } dependencies = [ { name = "langchain-core" }, @@ -2380,6 +2380,7 @@ dev = [ { name = "pytest-repeat" }, { name = "pytest-watcher" }, { name = "pytest-xdist", extras = ["psutil"] }, + { name = "redis" }, { name = "ruff" }, { name = "syrupy" }, { name = "types-requests" }, @@ -2413,6 +2414,7 @@ dev = [ { name = "pytest-asyncio" }, { name = "pytest-mock" }, { name = "pytest-watcher" }, + { name = "redis" }, { name = "ruff" }, ] @@ -2643,7 +2645,7 @@ test = [ [[package]] name = "langgraph-prebuilt" -version = "0.6.2" +version = "0.6.4" source = { editable = "../libs/prebuilt" } dependencies = [ { name = "langchain-core" }, @@ -2674,7 +2676,6 @@ dev = [ [[package]] name = "langgraph-sdk" -version = "0.2.0" source = { editable = "../libs/sdk-py" } dependencies = [ { name = "httpx" },