Skip to content

The agent engineering platform.

docs: show beta directive (#25013)

Bagatur1dcee68cb877
diff --git a/docs/api_reference/conf.py b/docs/api_reference/conf.py
index 6e4ed759f3..da4bec3082 100644
--- a/docs/api_reference/conf.py
+++ b/docs/api_reference/conf.py
@@ -15,6 +15,8 @@ from pathlib import Path
import toml
from docutils import nodes
+from docutils.parsers.rst.directives.admonitions import BaseAdmonition
+from docutils.statemachine import StringList
from sphinx.util.docutils import SphinxDirective
# If extensions (or modules to document with autodoc) are in another directory,
@@ -66,8 +68,23 @@ class ExampleLinksDirective(SphinxDirective):
return [list_node]
+class Beta(BaseAdmonition):
+ required_arguments = 0
+ node_class = nodes.admonition
+
+ def run(self):
+ self.content = self.content or StringList(
+ [
+ "This feature is in beta. It is actively being worked on, so the API may change."
+ ]
+ )
+ self.arguments = self.arguments or ["Beta"]
+ return super().run()
+
+
def setup(app):
app.add_directive("example_links", ExampleLinksDirective)
+ app.add_directive("beta", Beta)
# -- Project information -----------------------------------------------------
diff --git a/docs/api_reference/themes/scikit-learn-modern/static/css/theme.css b/docs/api_reference/themes/scikit-learn-modern/static/css/theme.css
index 1036c45821..2fbbee2cb8 100644
--- a/docs/api_reference/themes/scikit-learn-modern/static/css/theme.css
+++ b/docs/api_reference/themes/scikit-learn-modern/static/css/theme.css
@@ -897,6 +897,13 @@ div.admonition {
background-color: #eee;
}
+div.admonition-beta {
+ color: #d35400; /* A darker rich orange color */
+ background-color: #FDF2E9; /* A light orange-tinted background color */
+ border-color: #E59866; /* A darker soft orange border color */
+}
+
+
div.admonition p:last-child,
div.admonition dl:last-child,
div.admonition dd:last-child,
diff --git a/libs/core/langchain_core/_api/beta_decorator.py b/libs/core/langchain_core/_api/beta_decorator.py
index a481f10338..9ad1cd545f 100644
--- a/libs/core/langchain_core/_api/beta_decorator.py
+++ b/libs/core/langchain_core/_api/beta_decorator.py
@@ -212,25 +212,10 @@ def beta(
wrapper.__doc__ = new_doc
return cast(T, wrapper)
- old_doc = inspect.cleandoc(old_doc or "").strip("\n")
-
- # old_doc can be None
- if not old_doc:
- old_doc = ""
-
- # Modify the docstring to include a beta notice.
- notes_header = "\nNotes\n-----"
- components = [
- message,
- addendum,
- ]
+ old_doc = inspect.cleandoc(old_doc or "").strip("\n") or ""
+ components = [message, addendum]
details = " ".join([component.strip() for component in components if component])
- new_doc = (
- f"[*Beta*] {old_doc}\n"
- f"{notes_header if notes_header not in old_doc else ''}\n"
- f".. beta::\n"
- f" {details}"
- )
+ new_doc = f".. beta::\n" f" {details}\n\n" f"{old_doc}\n"
if inspect.iscoroutinefunction(obj):
finalized = finalize(awarning_emitting_wrapper, new_doc)
diff --git a/libs/core/tests/unit_tests/_api/test_beta_decorator.py b/libs/core/tests/unit_tests/_api/test_beta_decorator.py
index 634773344c..ef7dd11068 100644
--- a/libs/core/tests/unit_tests/_api/test_beta_decorator.py
+++ b/libs/core/tests/unit_tests/_api/test_beta_decorator.py
@@ -114,7 +114,7 @@ def test_beta_function() -> None:
doc = beta_function.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")
assert not inspect.iscoroutinefunction(beta_function)
@@ -134,7 +134,7 @@ async def test_beta_async_function() -> None:
doc = beta_function.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")
assert inspect.iscoroutinefunction(beta_async_function)
@@ -155,7 +155,7 @@ def test_beta_method() -> None:
doc = obj.beta_method.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")
assert not inspect.iscoroutinefunction(obj.beta_method)
@@ -176,7 +176,7 @@ async def test_beta_async_method() -> None:
doc = obj.beta_method.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")
assert inspect.iscoroutinefunction(obj.beta_async_method)
@@ -195,7 +195,7 @@ def test_beta_classmethod() -> None:
doc = ClassWithBetaMethods.beta_classmethod.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")
def test_beta_staticmethod() -> None:
@@ -214,7 +214,7 @@ def test_beta_staticmethod() -> None:
)
doc = ClassWithBetaMethods.beta_staticmethod.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")
def test_beta_property() -> None:
@@ -234,7 +234,7 @@ def test_beta_property() -> None:
)
doc = ClassWithBetaMethods.beta_property.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")
def test_whole_class_beta() -> None:
@@ -277,7 +277,7 @@ def test_whole_class_inherited_beta() -> None:
"""Test whole class beta status for inherited class.
The original version of beta decorator created duplicates with
- '[*Beta*]'.
+ '.. beta::'.
"""
# Test whole class beta status
@@ -339,9 +339,9 @@ def test_whole_class_inherited_beta() -> None:
"the API may change."
)
- # if [*Beta*] was inserted only once:
+ # if .. beta:: was inserted only once:
if obj.__doc__ is not None:
- assert obj.__doc__.count("[*Beta*]") == 1
+ assert obj.__doc__.count(".. beta::") == 1
# Tests with pydantic models
@@ -368,4 +368,4 @@ def test_beta_method_pydantic() -> None:
doc = obj.beta_method.__doc__
assert isinstance(doc, str)
- assert doc.startswith("[*Beta*] original doc")
+ assert doc.startswith(".. beta::")