From 1dcee68cb877cdffe513bbb025e896d40789dee8 Mon Sep 17 00:00:00 2001 From: Bagatur <22008038+baskaryan@users.noreply.github.com> Date: Fri, 2 Aug 2024 20:07:45 -0700 Subject: [PATCH] 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 | 17 ++++++++++++++ .../scikit-learn-modern/static/css/theme.css | 7 ++++++ .../langchain_core/_api/beta_decorator.py | 21 +++--------------- .../unit_tests/_api/test_beta_decorator.py | 22 +++++++++---------- 4 files changed, 38 insertions(+), 29 deletions(-) diff --git a/docs/api_reference/conf.py b/docs/api_reference/conf.py index 6e4ed759f3c..da4bec30828 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 1036c458216..2fbbee2cb84 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 a481f10338f..9ad1cd545f0 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 634773344ce..ef7dd110687 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::")