docs: more standardization (#33124)

Author: mdrxy

docs/api_reference/create_api_rst.py

@@ -214,7 +214,7 @@ def _load_package_modules(
     Traversal based on the file system makes it easy to determine which
     of the modules/packages are part of the package vs. 3rd party or built-in.
 
-    Parameters:
+    Args:
         package_directory: Path to the package directory.
         submodule: Optional name of submodule to load.
 

libs/cli/pyproject.toml

@@ -70,11 +70,14 @@ flake8-annotations.allow-star-arg-any = true
 flake8-annotations.mypy-init-return = true
 flake8-type-checking.runtime-evaluated-base-classes = ["pydantic.BaseModel","langchain_core.load.serializable.Serializable","langchain_core.runnables.base.RunnableSerializable"]
 pep8-naming.classmethod-decorators = [ "classmethod", "langchain_core.utils.pydantic.pre_init", "pydantic.field_validator", "pydantic.v1.root_validator",]
-pydocstyle.convention = "google"
 pyupgrade.keep-runtime-typing = true
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+ignore-var-parameters = true  # ignore missing documentation for *args and **kwargs parameters
+
 [tool.ruff.lint.per-file-ignores]
-"tests/**" = [ "D1", "DOC", "S", "SLF",]
+"tests/**" = [ "D1", "S", "SLF",]
 "scripts/**" = [ "INP", "S",]
 
 [tool.pytest.ini_options]

libs/cli/scripts/__init__.py

@@ -227,17 +227,17 @@ def warn_beta(
 ) -> None:
     """Display a standardized beta annotation.
 
-    Arguments:
-        message : str, optional
+    Args:
+        message:
             Override the default beta message. The
             %(name)s, %(obj_type)s, %(addendum)s
             format specifiers will be replaced by the
             values of the respective arguments passed to this function.
-        name : str, optional
+        name:
             The name of the annotated object.
-        obj_type : str, optional
+        obj_type:
             The object type being annotated.
-        addendum : str, optional
+        addendum:
             Additional text appended directly to the final message.
     """
     if not message:

libs/core/langchain_core/_api/beta_decorator.py

@@ -431,35 +431,35 @@ def warn_deprecated(
 ) -> None:
     """Display a standardized deprecation.
 
-    Arguments:
-        since : str
+    Args:
+        since:
             The release at which this API became deprecated.
-        message : str, optional
+        message:
             Override the default deprecation message. The %(since)s,
             %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,
             and %(removal)s format specifiers will be replaced by the
             values of the respective arguments passed to this function.
-        name : str, optional
+        name:
             The name of the deprecated object.
-        alternative : str, optional
+        alternative:
             An alternative API that the user may use in place of the
             deprecated API. The deprecation warning will tell the user
             about this alternative if provided.
-        alternative_import: str, optional
+        alternative_import:
             An alternative import that the user may use instead.
-        pending : bool, optional
+        pending:
             If True, uses a PendingDeprecationWarning instead of a
             DeprecationWarning. Cannot be used together with removal.
-        obj_type : str, optional
+        obj_type:
             The object type being deprecated.
-        addendum : str, optional
+        addendum:
             Additional text appended directly to the final message.
-        removal : str, optional
+        removal:
             The expected removal version. With the default (an empty
             string), a removal version is automatically computed from
             since. Set to other Falsy values to not schedule a removal
             date. Cannot be used together with pending.
-        package: str, optional
+        package:
             The package of the deprecated object.
     """
     if not pending:

libs/core/langchain_core/_api/deprecation.py

@@ -111,7 +111,7 @@ class Serializable(BaseModel, ABC):
 
     # Remove default BaseModel init docstring.
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        """"""  # noqa: D419
+        """"""  # noqa: D419  # Intentional blank docstring
         super().__init__(*args, **kwargs)
 
     @classmethod

libs/core/langchain_core/load/serializable.py

@@ -227,7 +227,7 @@ def invalid_docstring_3(bar: str, baz: int) -> str:
                 \"\"\"
                 return bar
 
-    """  # noqa: D214, D410, D411
+    """  # noqa: D214, D410, D411  # We're intentionally showing bad formatting in examples
 
     def _create_tool_factory(
         tool_name: str,

libs/core/langchain_core/tools/convert.py

@@ -667,14 +667,13 @@ def tool_example_to_messages(
     The ``ToolMessage`` is required because some chat models are hyper-optimized for
     agents rather than for an extraction use case.
 
-    Arguments:
-        input: string, the user input
-        tool_calls: list[BaseModel], a list of tool calls represented as Pydantic
-            BaseModels
-        tool_outputs: Optional[list[str]], a list of tool call outputs.
+    Args:
+        input: The user input
+        tool_calls: Tool calls represented as Pydantic BaseModels
+        tool_outputs: Tool call outputs.
             Does not need to be provided. If not provided, a placeholder value
             will be inserted. Defaults to None.
-        ai_response: Optional[str], if provided, content for a final ``AIMessage``.
+        ai_response: If provided, content for a final ``AIMessage``.
 
     Returns:
         A list of messages

libs/core/langchain_core/utils/function_calling.py

@@ -99,7 +99,6 @@ ignore = [
     # TODO rules
     "ANN401",  # No Any types
     "BLE",     # Blind exceptions
-    "DOC",     # Docstrings (preview)
     "ERA",     # No commented-out code
     "PLR2004", # Comparison to magic number
 ]
@@ -113,10 +112,12 @@ flake8-annotations.mypy-init-return = true
 flake8-builtins.ignorelist = ["id", "input", "type"]
 flake8-type-checking.runtime-evaluated-base-classes = ["pydantic.BaseModel","langchain_core.load.serializable.Serializable","langchain_core.runnables.base.RunnableSerializable"]
 pep8-naming.classmethod-decorators = [ "classmethod", "langchain_core.utils.pydantic.pre_init", "pydantic.field_validator", "pydantic.v1.root_validator",]
-pydocstyle.convention = "google"
-pydocstyle.ignore-var-parameters = true
 pyupgrade.keep-runtime-typing = true
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+ignore-var-parameters = true  # ignore missing documentation for *args and **kwargs parameters
+
 [tool.ruff.lint.per-file-ignores]
 "langchain_core/utils/mustache.py" = [ "PLW0603",]
 "tests/unit_tests/test_tools.py" = [ "ARG",]

libs/core/pyproject.toml

@@ -1344,7 +1344,7 @@ def foo4(bar: str, baz: int) -> str:
         Args:
             bar: The bar.
             baz: The baz.
-        """  # noqa: D205,D411
+        """  # noqa: D205,D411  # We're intentionally testing bad formatting.
         return bar
 
     for func in {foo3, foo4}: