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/
2026-08-17 21:25:46 +02:00 · 2025-09-25 17:07:00 +00:00
parent 90ac06deb6
commit 4101aebeea
2 changed files with 137 additions and 18 deletions
@@ -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

@@ -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."