docs: show beta directive (#25013)

![Screenshot 2024-08-02 at 7 15 34
PM](https://github.com/user-attachments/assets/086831c7-36f3-4962-98dc-d707b6289747)

docs/api_reference/conf.py

@@ -15,6 +15,8 @@
 
 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 @@ def run(self):
         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 -----------------------------------------------------

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,

libs/core/langchain_core/_api/beta_decorator.py

@@ -212,25 +212,10 @@ def finalize(wrapper: Callable[..., Any], new_doc: str) -> T:
                 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)

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 beta_method(self) -> str:
             "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::")