From 4101aebeeaa424634b1326ae286d510ad5eb57e8 Mon Sep 17 00:00:00 2001 From: Mason Daugherty Date: Thu, 25 Sep 2025 13:07:00 -0400 Subject: [PATCH] chore(langgraph): clean up ruff format config (#6188) Each of the settings present are already defaults in the ruff config: https://docs.astral.sh/ruff/settings/ --- docs/README.md | 147 +++++++++++++++++++++++++++++++--- libs/langgraph/pyproject.toml | 8 -- 2 files changed, 137 insertions(+), 18 deletions(-) diff --git a/docs/README.md b/docs/README.md index 369f196a2..31a2c89c7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,24 +1,150 @@ -# Setup +# LangGraph Documentation -To setup requirements for building docs you can run: +For more information on contributing to our documentation, see the [Contributing Guide](../CONTRIBUTING.md). -```bash -uv sync --group test +## Structure + +The primary documentation is located in the `docs/` directory. This directory contains both the source files for the main documentation as well as the API reference doc build process. + +### Main Documentation + +Main documentation files are located in `docs/docs/` and are written in Markdown format. The site uses [**MkDocs**](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) and includes: + +- **Concepts**: Core LangGraph concepts and explanations +- **Tutorials**: Step-by-step learning guides +- **How-tos**: Task-focused guides for specific use cases +- **Examples**: Real-world applications and use cases +- **Jupyter Notebooks**: Interactive tutorials that are automatically converted to 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: + +```markdown +::: langgraph.graph.state.StateGraph + options: + members: + - add_node + - compile ``` -## Serving documentation locally +#### Build Process -To run the documentation server locally you can run: +The build process follows these steps: + +1. **Content Processing Phase:** + - `_scripts/notebook_hooks.py` - Main processing pipeline that: + - Converts 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 + - Cross-references are automatically generated between docs and API + +3. **Site Generation:** + - **MkDocs** processes all markdown files and generates static HTML + - Custom hooks handle redirects and inject additional functionality + +4. **Deployment:** + - Site is deployed with Vercel + - `make build-docs` generates production build (also usable for local testing) + - Automatic redirects handle URL changes between versions + +#### Local Development + +For local development, use the Makefile targets: ```bash +# Serve docs locally with hot reloading make serve-docs + +# Clean build for production testing +make build-docs + +# Serve with clean build +make serve-clean-docs ``` -This will start the documentation server on [http://127.0.0.1:8000/langgraph/](http://127.0.0.1:8000/langgraph/). +The `serve-docs` command: + +- Watches source files for changes +- Includes dirty builds for faster iteration +- Serves on [http://127.0.0.1:8000/langgraph/](http://127.0.0.1:8000/langgraph/) + +#### Documentation Standards + +**Docstring Format:** +The API reference uses **Google-style docstrings** with Markdown markup. The `mkdocstrings` plugin processes these to generate documentation. + +**Required format:** + +```python +def example_function(param1: str, param2: int = 5) -> bool: + """Brief description of the function. + + Longer description can go here. Use Markdown syntax for + rich formatting like **bold** and *italic*. + + Args: + param1: Description of the first parameter. + param2: Description of the second parameter with default value. + + Returns: + Description of the return value. + + Raises: + ValueError: When param1 is empty. + TypeError: When param2 is not an integer. + + !!! warning + This function is experimental and may change. + + !!! version-added "Added in version 0.2.0" + """ +``` + +**Special Markers:** + +- **MkDocs admonitions**: `!!! warning`, `!!! note`, `!!! version-added` +- **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" GHA, you can run: +If you would like to automatically execute all of the notebooks, to mimic the "Run notebooks" GitHub action, you can run: ```bash python _scripts/prepare_notebooks_for_ci.py @@ -33,8 +159,9 @@ python _scripts/prepare_notebooks_for_ci.py --comment-install-cells ``` `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 + +- 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 ## Adding new notebooks diff --git a/libs/langgraph/pyproject.toml b/libs/langgraph/pyproject.toml index b575ad754..178e2b56a 100644 --- a/libs/langgraph/pyproject.toml +++ b/libs/langgraph/pyproject.toml @@ -74,14 +74,6 @@ target-version = "py39" [tool.ruff.lint.per-file-ignores] "tests/bench/*" = ["UP006", "UP007"] -[tool.ruff.format] -quote-style = "double" -indent-style = "space" -skip-magic-trailing-comma = false -line-ending = "auto" -docstring-code-format = false -docstring-code-line-length = "dynamic" - [tool.ruff.lint.flake8-tidy-imports.banned-api] "typing.TypedDict".msg = "Use typing_extensions.TypedDict instead."