Repository: langchain-ai/langgraph
Pull request #3988: docs: add version admonitions for `Interrupt` and `RetryPolicy`
Author: login: YassinNouh21
Created: 2025-03-23T00:55:27Z | Merged: 2025-03-26T17:48:54Z

This pull request includes changes to add version admonitions to the documentation and update the styling for these admonitions. The most important changes include the addition of version information to the documentation, updates to the CSS for version admonitions, and modifications to the `mkdocs.yml` configuration file to include the new stylesheets.
this should solve this langchain-ai/docs#476 



Diff:
diff --git a/docs/docs/stylesheets/version_admonitions.css b/docs/docs/stylesheets/version_admonitions.css
new file mode 100644
index 00000000000..a8fcb642993
--- /dev/null
+++ b/docs/docs/stylesheets/version_admonitions.css
@@ -0,0 +1,38 @@
+:root {
+  --md-admonition-icon--version-added: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h4l3 3 3-3h4c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2m0 16h-4.2l-.8.8-2 2-2-2-.8-.8H5V4h14z"/><path d="M11 15h2v2h-2v-2m0-10h2v8h-2V5"/></svg>');
+  --md-admonition-icon--version-changed: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h4l3 3 3-3h4c1.1 0 2-.9 2-2V4c0-1.1-.9-2-2-2m0 16h-4.2l-.8.8-2 2-2-2-.8-.8H5V4h14z"/><path d="M15 11h-2V9h-2v2H9v2h2v2h2v-2h2v-2Z"/></svg>');
+}
+
+.md-typeset .admonition.version-added,
+.md-typeset details.version-added {
+  border-color: rgb(0, 191, 165);
+}
+
+.md-typeset .version-added > .admonition-title,
+.md-typeset .version-added > summary {
+  background-color: rgba(0, 191, 165, 0.1);
+}
+
+.md-typeset .version-added > .admonition-title::before,
+.md-typeset .version-added > summary::before {
+  background-color: rgb(0, 191, 165);
+  -webkit-mask-image: var(--md-admonition-icon--version-added);
+          mask-image: var(--md-admonition-icon--version-added);
+}
+
+.md-typeset .admonition.version-changed,
+.md-typeset details.version-changed {
+  border-color: rgb(100, 221, 23);
+}
+
+.md-typeset .version-changed > .admonition-title,
+.md-typeset .version-changed > summary {
+  background-color: rgba(100, 221, 23, 0.1);
+}
+
+.md-typeset .version-changed > .admonition-title::before,
+.md-typeset .version-changed > summary::before {
+  background-color: rgb(100, 221, 23);
+  -webkit-mask-image: var(--md-admonition-icon--version-changed);
+          mask-image: var(--md-admonition-icon--version-changed);
+} 
\ No newline at end of file
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 697d6bdc4c4..049a6a4abb4 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -503,3 +503,5 @@ validation:
   not_found: info
 copyright: >
   Copyright &copy; 2025 LangChain, Inc | <a href="#__consent">Consent Preferences</a>
+extra_css:
+  - stylesheets/version_admonitions.css
diff --git a/libs/langgraph/langgraph/types.py b/libs/langgraph/langgraph/types.py
index 0a3e9f20583..6fb0b9b4a8f 100644
--- a/libs/langgraph/langgraph/types.py
+++ b/libs/langgraph/langgraph/types.py
@@ -101,7 +101,10 @@ def default_retry_on(exc: Exception) -> bool:
 
 
 class RetryPolicy(NamedTuple):
-    """Configuration for retrying nodes."""
+    """Configuration for retrying nodes.
+
+    !!! version-added "Added in version 0.2.24."
+    """
 
     initial_interval: float = 0.5
     """Amount of time that must elapse before the first retry occurs. In seconds."""
@@ -120,13 +123,20 @@ class RetryPolicy(NamedTuple):
 
 
 class CachePolicy(NamedTuple):
-    """Configuration for caching nodes."""
+    """Configuration for caching nodes.
+
+    !!! version-added "Added in version 0.2.24."
+    """
 
     pass
 
 
 @dataclasses.dataclass(**_DC_KWARGS)
 class Interrupt:
+    """
+    !!! version-added "Added in version 0.2.24."
+    """
+
     value: Any
     resumable: bool = False
     ns: Optional[Sequence[str]] = None
@@ -268,6 +278,8 @@ def __eq__(self, value: object) -> bool:
 class Command(Generic[N], ToolOutputMixin):
     """One or more commands to update the graph's state and send messages to nodes.
 
+    !!! version-added "Added in version 0.2.24."
+
     Args:
         graph: graph to send the command to. Supported values are:
 


Reviews:
user: login: eyurtsev
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-24T17:02:25Z
user: login: YassinNouh21
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-24T17:28:45Z
user: login: eyurtsev
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-24T18:43:13Z
user: login: eyurtsev
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-25T15:05:16Z
user: login: eyurtsev
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-03-25T15:23:45Z
user: login: eyurtsev
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-25T19:45:21Z
user: login: eyurtsev
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-03-26T17:41:34Z

Review comments:
diff_hunk: @@ -0,0 +1,44 @@
+# Testing Version Admonitions
path: docs/cassettes/test_versions.md
user: login: eyurtsev
body: Let's remove this file.

Have you tried serving docs locally to check if ti works for the API reference?

`make serve-docs`
created_at: 2025-03-24T17:00:20Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,44 @@
+# Testing Version Admonitions
path: docs/cassettes/test_versions.md
user: login: YassinNouh21
body: @eyurtsev 
I've removed the test_versions.md file and updated the mkdocs.yml configuration to remove its reference. The documentation should now build without the test versions page.

I've also tried serving the docs locally with `make serve-docs` to verify the changes. The documentation server is running and you can check the API reference at http://localhost:8000.
created_at: 2025-03-24T17:28:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -101,7 +101,10 @@ def default_retry_on(exc: Exception) -> bool:
 
 
 class RetryPolicy(NamedTuple):
-    """Configuration for retrying nodes."""
+    """
+    !!! version-added "Added in v0.2.24"
path: libs/langgraph/langgraph/types.py
user: login: eyurtsev
body: ```suggestion
    !!! version-added "0.2.24"
```
created_at: 2025-03-24T18:41:57Z
author_association: COLLABORATOR
diff_hunk: @@ -101,7 +101,10 @@ def default_retry_on(exc: Exception) -> bool:
 
 
 class RetryPolicy(NamedTuple):
-    """Configuration for retrying nodes."""
+    """
path: libs/langgraph/langgraph/types.py
user: login: eyurtsev
body: Let's restore the object descriptions.

```suggestion
    """Configuration for retrying nodes.
```
created_at: 2025-03-24T18:42:10Z
author_association: COLLABORATOR
diff_hunk: @@ -101,7 +101,10 @@ def default_retry_on(exc: Exception) -> bool:
 
 
 class RetryPolicy(NamedTuple):
-    """Configuration for retrying nodes."""
+    """
+    !!! version-added "Added in v0.2.24"
+        The RetryPolicy class was introduced in version 0.2.24 (September 2024).
path: libs/langgraph/langgraph/types.py
user: login: eyurtsev
body: This doesn't provide any additional information. We just want a minimal version added.

```suggestion
```

---

A description could be useful if we start using ..version-modified
created_at: 2025-03-24T18:42:56Z
author_association: COLLABORATOR
diff_hunk: @@ -120,13 +123,18 @@ class RetryPolicy(NamedTuple):
 
 
 class CachePolicy(NamedTuple):
-    """Configuration for caching nodes."""
+    """
path: libs/langgraph/langgraph/types.py
user: login: eyurtsev
body: ```suggestion
    """Configuration for caching nodes.
```
created_at: 2025-03-25T15:03:49Z
author_association: COLLABORATOR
diff_hunk: @@ -101,7 +101,10 @@ def default_retry_on(exc: Exception) -> bool:
 
 
 class RetryPolicy(NamedTuple):
-    """Configuration for retrying nodes."""
+    """Configuration for retrying nodes.
+    
+    !!! version-added "Added in version 0.2.24."
path: libs/langgraph/langgraph/types.py
user: login: eyurtsev
body: Is there anyway to have "Added in version" be prepended automatically, so that we only put the version?
created_at: 2025-03-25T15:05:10Z
author_association: COLLABORATOR
diff_hunk: @@ -120,13 +123,18 @@ class RetryPolicy(NamedTuple):
 
 
 class CachePolicy(NamedTuple):
-    """Configuration for caching nodes."""
+    """
path: libs/langgraph/langgraph/types.py
user: login: eyurtsev
body: Could you restore the title? we shouldn't delete the doc-strings for types when adding versions
created_at: 2025-03-25T19:44:44Z
author_association: COLLABORATOR
diff_hunk: @@ -417,7 +428,7 @@ def node(state: State):
                 # as part of the interrupt information.
                 \"what is your age?\"
             )
-            print(f\"> Received an input from the interrupt: {answer}\")
+            print(f"> Received an input from the interrupt: {answer}\")
path: libs/langgraph/langgraph/types.py
user: login: eyurtsev
body: I believe the `\` is necessary in this case

```suggestion
            print(f"> Received an input from the interrupt: {answer}\")
```
created_at: 2025-03-25T19:45:17Z
author_association: COLLABORATOR

PR comments:
user: login: vercel[bot]
created_at: 2025-03-23T00:55:31Z
body: [vc]: #f1AkKf22YBYW7kOSeS1H7bulhisKtosc+JNU3pWbWA4=:eyJpc01vbm9yZXBvIjp0cnVlLCJ0eXBlIjoiZ2l0aHViIiwicHJvamVjdHMiOlt7Im5hbWUiOiJsYW5nZ3JhcGgtZG9jcy1wcmV2aWV3IiwiaW5zcGVjdG9yVXJsIjoiaHR0cHM6Ly92ZXJjZWwuY29tL2xhbmdjaGFpbi9sYW5nZ3JhcGgtZG9jcy1wcmV2aWV3L0ZBTDVLcGlDQm55VDhKY1dTeVVqNE5pQUZ0QkIiLCJwcmV2aWV3VXJsIjoibGFuZ2dyYXBoLWRvY3MtcHJldmlldy1naXQtZm9yay15YXNzaW5ub3VoMjEtZi04Nzk1OGItbGFuZ2NoYWluLnZlcmNlbC5hcHAiLCJuZXh0Q29tbWl0U3RhdHVzIjoiSUdOT1JFRCIsImxpdmVGZWVkYmFjayI6eyJyZXNvbHZlZCI6MCwidW5yZXNvbHZlZCI6MCwidG90YWwiOjAsImxpbmsiOiIifSwicm9vdERpcmVjdG9yeSI6ImRvY3MifV19
**The latest updates on your projects**. Learn more about [Vercel for Git ↗︎](https://vercel.link/github-learn-more)


<details><summary>1 Skipped Deployment</summary>

| Name | Status | Preview | Comments | Updated (UTC) |
| :--- | :----- | :------ | :------- | :------ |
| **langgraph-docs-preview** | ⬜️ Ignored ([Inspect](https://vercel.com/langchain/langgraph-docs-preview/FAL5KpiCBnyT8JcWSyUj4NiAFtBB)) | [Visit Preview](https://langgraph-docs-preview-git-fork-yassinnouh21-f-87958b-langchain.vercel.app) |  | Mar 25, 2025 8:07pm |
</details>


author_association: NONE
user: login: eyurtsev
created_at: 2025-03-24T18:45:52Z
body: Cool it looks like this is I make it minimal.

Is there a way to add a title saying "Added in version {version}." by default?

Here's how it looks like:

![image](https://github.com/user-attachments/assets/160ecb46-2cc2-456a-ba1e-552fe5d68011)


Here's a default from rst / sphinx:

![image](https://github.com/user-attachments/assets/25b6cea5-ae9b-4991-8d67-4a180010b28c)

author_association: COLLABORATOR
user: login: eyurtsev
created_at: 2025-03-25T15:23:22Z
body: @YassinNouh21 I'm going to merge this change. If you can figure out how to make the prepending automatic, please follow up with a PR for that! Would be appreciated. 

We want the syntax to just be ` !!! version-added "0.2.24" inside the code, and anything else to be done by mkdocs
author_association: COLLABORATOR
user: login: YassinNouh21
created_at: 2025-03-25T15:51:16Z
body: @eyurtsev I solved the issue in the ci for python linter 3.12 
now I think it is ready for merge 
author_association: CONTRIBUTOR
user: login: YassinNouh21
created_at: 2025-03-25T18:50:58Z
body: @eyurtsev it is ok can u merge 
author_association: CONTRIBUTOR
user: login: YassinNouh21
created_at: 2025-03-26T11:01:04Z
body: Hey @eyurtsev ,

I've found configuration in the `mkdocs.yml` that allows us to automatically prepend "Added in version" to the version admonitions. Specifically, we've set up the `markdown_version_annotations` plugin with this configuration:

```yaml
- markdown_version_annotations:
    version_added_title: "Added in version \\1"
```

This means when we use `+++ 0.2.24` or `!!! version-added "0.2.24"`, it will automatically generate an admonition that says "Added in version 0.2.24".

Let me know what you think!
author_association: CONTRIBUTOR
user: login: eyurtsev
created_at: 2025-03-26T17:43:56Z
body: @YassinNouh21 good find! I think it's a good solution, but I would like to vendor it in rather than rely on an external dependency. 

It's under an MIT license: https://github.com/glennmatthews/markdown-version-annotations/blob/main/pyproject.toml#L6

So we can copy paste the code with appropriate attribution (i.e., to give credit to the original implementation) and hook it up. If you're interested in doing that, you can create a vendored version under _scripts and figure out how to hook it up (could potentially do it via the hook system rather than as a plugin)
author_association: COLLABORATOR