docs: standardize .. code-block directive usage (#33122)

and fix typos

docs/api_reference/_extensions/gallery_directive.py

@@ -50,7 +50,7 @@ class GalleryGridDirective(SphinxDirective):
     individual cards + ["image", "header", "content", "title"].
 
     Danger:
-        This directive can only be used in the context of a Myst documentation page as
+        This directive can only be used in the context of a MyST documentation page as
         the templates use Markdown flavored formatting.
     """
 

docs/api_reference/conf.py

@@ -126,7 +126,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinxcontrib.autodoc_pydantic",
     "IPython.sphinxext.ipython_console_highlighting",
-    "myst_parser",
+    "myst_parser",  # For generated index.md and reference.md
     "_extensions.gallery_directive",
     "sphinx_design",
     "sphinx_copybutton",
@@ -259,20 +259,8 @@ html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
 html_use_index = False
 
-myst_enable_extensions = [
-    "colon_fence",  # ::: directive blocks (existing prior to LangGraph support)
-    # LangGraph compatibility extensions added for consolidation
-    # TODO: check for presence of each in LangGraph and only enable if needed
-    # "deflist",  # Definition lists
-    # "tasklist",  # - [ ] checkboxes (common in examples)
-    # "attrs_inline",  # {.class} inline attributes (MkDocs style)
-    # "attrs_block",  # Block-level attributes
-    # "substitution",  # Variable substitution
-    # "linkify",  # Auto-link URLs in text
-    # Math extensions (uncomment if LangGraph uses mathematical notation)
-    # "dollarmath",     # $ math $ inline math
-    # "amsmath",        # Advanced math environments
-]
+# Only used on the generated index.md and reference.md files
+myst_enable_extensions = ["colon_fence"]
 
 # generate autosummary even if no references
 autosummary_generate = True

docs/api_reference/requirements.txt

@@ -6,7 +6,7 @@ sphinx-copybutton
 sphinxcontrib-googleanalytics
 pydata-sphinx-theme>=0.15
 myst-parser>=3
-toml>=0.10.2
 myst-nb>=1.1.1
+toml>=0.10.2
 pyyaml
 beautifulsoup4

libs/cli/langchain_cli/integration_template/integration_template/retrievers.py

@@ -46,7 +46,7 @@ class __ModuleName__Retriever(BaseRetriever):
 
             retriever.invoke(query)
 
-        .. code-block:: none
+        .. code-block::
 
             # TODO: Example output.
 
@@ -80,7 +80,7 @@ class __ModuleName__Retriever(BaseRetriever):
 
             chain.invoke("...")
 
-        .. code-block:: none
+        .. code-block::
 
              # TODO: Example output.
 

libs/cli/langchain_cli/integration_template/integration_template/toolkits.py

@@ -42,7 +42,7 @@ class __ModuleName__Toolkit(BaseToolkit):
 
             toolkit.get_tools()
 
-        .. code-block:: none
+        .. code-block::
 
             # TODO: Example output.
 
@@ -62,7 +62,7 @@ class __ModuleName__Toolkit(BaseToolkit):
             for event in events:
                 event["messages"][-1].pretty_print()
 
-        .. code-block:: none
+        .. code-block::
 
              # TODO: Example output.
 

libs/core/langchain_core/callbacks/manager.py

@@ -92,7 +92,7 @@ def trace_as_chain_group(
         metadata (dict[str, Any], optional): The metadata to apply to all runs.
             Defaults to None.
 
-    .. note:
+    .. note::
         Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
         LangSmith.
 
@@ -179,7 +179,7 @@ async def atrace_as_chain_group(
     Yields:
         The async callback manager for the chain group.
 
-    .. note:
+    .. note::
         Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
         LangSmith.
 

libs/core/langchain_core/callbacks/usage.py

@@ -32,7 +32,7 @@ class UsageMetadataCallbackHandler(BaseCallbackHandler):
             result_2 = llm_2.invoke("Hello", config={"callbacks": [callback]})
             callback.usage_metadata
 
-        .. code-block:: none
+        .. code-block::
 
             {'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
               'output_tokens': 10,
@@ -119,7 +119,7 @@ def get_usage_metadata_callback(
                 llm_2.invoke("Hello")
                 print(cb.usage_metadata)
 
-        .. code-block:: none
+        .. code-block::
 
             {'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
               'output_tokens': 10,

libs/core/langchain_core/document_loaders/langsmith.py

@@ -31,7 +31,7 @@ class LangSmithLoader(BaseLoader):
             for doc in loader.lazy_load():
                 docs.append(doc)
 
-        .. code-block:: pycon
+        .. code-block:: python
 
             # -> [Document("...", metadata={"inputs": {...}, "outputs": {...}, ...}), ...]
 

libs/core/langchain_core/indexing/api.py

@@ -296,7 +296,11 @@ def index(
     For the time being, documents are indexed using their hashes, and users
     are not able to specify the uid of the document.
 
-    Important:
+    .. versionchanged:: 0.3.25
+        Added ``scoped_full`` cleanup mode.
+
+    .. important::
+
         * In full mode, the loader should be returning
           the entire dataset, and not just a subset of the dataset.
           Otherwise, the auto_cleanup will remove documents that it is not
@@ -309,7 +313,7 @@ def index(
           chunks, and we index them using a batch size of 5, we'll have 3 batches
           all with the same source id. In general, to avoid doing too much
           redundant work select as big a batch size as possible.
-        * The `scoped_full` mode is suitable if determining an appropriate batch size
+        * The ``scoped_full`` mode is suitable if determining an appropriate batch size
           is challenging or if your data loader cannot return the entire dataset at
           once. This mode keeps track of source IDs in memory, which should be fine
           for most use cases. If your dataset is large (10M+ docs), you will likely
@@ -378,10 +382,6 @@ def index(
         TypeError: If ``vectorstore`` is not a VectorStore or a DocumentIndex.
         AssertionError: If ``source_id`` is None when cleanup mode is incremental.
             (should be unreachable code).
-
-    .. version_modified:: 0.3.25
-
-        * Added `scoped_full` cleanup mode.
     """
     # Behavior is deprecated, but we keep it for backwards compatibility.
     # # Warn only once per process.
@@ -636,26 +636,30 @@ async def aindex(
     documents were deleted, which documents should be skipped.
 
     For the time being, documents are indexed using their hashes, and users
-     are not able to specify the uid of the document.
+    are not able to specify the uid of the document.
 
-    Important:
-       * In full mode, the loader should be returning
-         the entire dataset, and not just a subset of the dataset.
-         Otherwise, the auto_cleanup will remove documents that it is not
-         supposed to.
-       * In incremental mode, if documents associated with a particular
-         source id appear across different batches, the indexing API
-         will do some redundant work. This will still result in the
-         correct end state of the index, but will unfortunately not be
-         100% efficient. For example, if a given document is split into 15
-         chunks, and we index them using a batch size of 5, we'll have 3 batches
-         all with the same source id. In general, to avoid doing too much
-         redundant work select as big a batch size as possible.
-       * The `scoped_full` mode is suitable if determining an appropriate batch size
-         is challenging or if your data loader cannot return the entire dataset at
-         once. This mode keeps track of source IDs in memory, which should be fine
-         for most use cases. If your dataset is large (10M+ docs), you will likely
-         need to parallelize the indexing process regardless.
+    .. versionchanged:: 0.3.25
+        Added ``scoped_full`` cleanup mode.
+
+    .. important::
+
+        * In full mode, the loader should be returning
+          the entire dataset, and not just a subset of the dataset.
+          Otherwise, the auto_cleanup will remove documents that it is not
+          supposed to.
+        * In incremental mode, if documents associated with a particular
+          source id appear across different batches, the indexing API
+          will do some redundant work. This will still result in the
+          correct end state of the index, but will unfortunately not be
+          100% efficient. For example, if a given document is split into 15
+          chunks, and we index them using a batch size of 5, we'll have 3 batches
+          all with the same source id. In general, to avoid doing too much
+          redundant work select as big a batch size as possible.
+        * The ``scoped_full`` mode is suitable if determining an appropriate batch size
+          is challenging or if your data loader cannot return the entire dataset at
+          once. This mode keeps track of source IDs in memory, which should be fine
+          for most use cases. If your dataset is large (10M+ docs), you will likely
+          need to parallelize the indexing process regardless.
 
     Args:
         docs_source: Data loader or iterable of documents to index.
@@ -720,10 +724,6 @@ async def aindex(
         TypeError: If ``vector_store`` is not a VectorStore or DocumentIndex.
         AssertionError: If ``source_id_key`` is None when cleanup mode is
             incremental or ``scoped_full`` (should be unreachable).
-
-    .. version_modified:: 0.3.25
-
-        * Added `scoped_full` cleanup mode.
     """
     # Behavior is deprecated, but we keep it for backwards compatibility.
     # # Warn only once per process.

libs/core/langchain_core/runnables/graph_ascii.py

@@ -269,7 +269,7 @@ def draw_ascii(vertices: Mapping[str, str], edges: Sequence[LangEdge]) -> str:
 
             print(draw_ascii(vertices, edges))
 
-        .. code-block:: none
+        .. code-block::
 
                  +---+
                  | 1 |

libs/core/langchain_core/utils/aiter.py

@@ -165,7 +165,7 @@ class Tee(Generic[T]):
     A ``tee`` works lazily and can handle an infinite ``iterable``, provided
     that all iterators advance.
 
-    .. code-block:: python3
+    .. code-block:: python
 
         async def derivative(sensor_data):
             previous, current = a.tee(sensor_data, n=2)

libs/core/langchain_core/utils/iter.py

@@ -102,7 +102,7 @@ class Tee(Generic[T]):
     A ``tee`` works lazily and can handle an infinite ``iterable``, provided
     that all iterators advance.
 
-    .. code-block:: python3
+    .. code-block:: python
 
         async def derivative(sensor_data):
             previous, current = a.tee(sensor_data, n=2)

libs/core/langchain_core/vectorstores/in_memory.py

@@ -94,7 +94,7 @@ class InMemoryVectorStore(VectorStore):
             for doc in results:
                 print(f"* {doc.page_content} [{doc.metadata}]")
 
-        .. code-block:: none
+        .. code-block::
 
             * thud [{'bar': 'baz'}]
 
@@ -111,7 +111,7 @@ class InMemoryVectorStore(VectorStore):
             for doc in results:
                 print(f"* {doc.page_content} [{doc.metadata}]")
 
-        .. code-block:: none
+        .. code-block::
 
             * thud [{'bar': 'baz'}]
 
@@ -123,7 +123,7 @@ class InMemoryVectorStore(VectorStore):
             for doc, score in results:
                 print(f"* [SIM={score:3f}] {doc.page_content} [{doc.metadata}]")
 
-        .. code-block:: none
+        .. code-block::
 
             * [SIM=0.832268] foo [{'baz': 'bar'}]
 
@@ -144,7 +144,7 @@ class InMemoryVectorStore(VectorStore):
             for doc, score in results:
                 print(f"* [SIM={score:3f}] {doc.page_content} [{doc.metadata}]")
 
-        .. code-block:: none
+        .. code-block::
 
             * [SIM=0.832268] foo [{'baz': 'bar'}]
 
@@ -157,7 +157,7 @@ class InMemoryVectorStore(VectorStore):
             )
             retriever.invoke("thud")
 
-        .. code-block:: none
+        .. code-block::
 
             [Document(id='2', metadata={'bar': 'baz'}, page_content='thud')]
 

libs/langchain/langchain/chains/llm_math/base.py

@@ -123,7 +123,7 @@ class LLMMathChain(Chain):
             async for event in events:
                 event["messages"][-1].pretty_print()
 
-        .. code-block:: none
+        .. code-block::
 
             ================================ Human Message =================================
 

libs/langchain/tests/unit_tests/chat_models/test_base.py

@@ -79,7 +79,7 @@ def test_configurable() -> None:
 
     Example:
 
-    .. python::
+    .. code-block:: python
 
         # This creates a configurable model without specifying which model
         model = init_chat_model()
@@ -88,10 +88,7 @@ def test_configurable() -> None:
         model.get_num_tokens("hello")  # AttributeError!
 
         # This works - provides model at runtime
-        response = model.invoke(
-            "Hello",
-            config={"configurable": {"model": "gpt-4o"}}
-        )
+        response = model.invoke("Hello", config={"configurable": {"model": "gpt-4o"}})
 
     """
     model = init_chat_model()
@@ -208,10 +205,12 @@ def test_configurable_with_default() -> None:
 
     Example:
 
-    .. python::
+    .. code-block:: python
 
         # This creates a configurable model with default parameters (model)
-        model = init_chat_model("gpt-4o", configurable_fields="any", config_prefix="bar")
+        model = init_chat_model(
+            "gpt-4o", configurable_fields="any", config_prefix="bar"
+        )
 
         # This works immediately - uses default gpt-4o
         tokens = model.get_num_tokens("hello")
@@ -219,10 +218,10 @@ def test_configurable_with_default() -> None:
         # This also works - switches to Claude at runtime
         response = model.invoke(
             "Hello",
-            config={"configurable": {"my_model_model": "claude-3-sonnet-20240229"}}
+            config={"configurable": {"my_model_model": "claude-3-sonnet-20240229"}},
         )
 
-    """  # noqa: E501
+    """
     model = init_chat_model("gpt-4o", configurable_fields="any", config_prefix="bar")
     for method in (
         "invoke",

libs/langchain_v1/langchain/agents/react_agent.py

@@ -985,10 +985,10 @@ def create_agent(  # noqa: D417
               of the list of messages in state["messages"].
             - SystemMessage: this is added to the beginning of the list of messages
               in state["messages"].
-            - Callable: This function should take in full graph state and the output is then passed
-              to the language model.
-            - Runnable: This runnable should take in full graph state and the output is then passed
-              to the language model.
+            - Callable: This function should take in full graph state and the output is
+              then passed to the language model.
+            - Runnable: This runnable should take in full graph state and the output is
+              then passed to the language model.
 
         response_format: An optional UsingToolStrategy configuration for structured responses.
 
@@ -1002,7 +1002,8 @@ def create_agent(  # noqa: D417
 
                 - schemas: A sequence of ResponseSchema objects that define
                   the structured output format
-                - tool_choice: Either "required" or "auto" to control when structured output is used
+                - tool_choice: Either "required" or "auto" to control when structured
+                  output is used
 
             Each ResponseSchema contains:
 
@@ -1015,8 +1016,8 @@ def create_agent(  # noqa: D417
                 `response_format` requires the model to support tool calling
 
             .. note::
-                Structured responses are handled directly in the model call node via tool calls,
-                eliminating the need for separate structured response nodes.
+                Structured responses are handled directly in the model call node via
+                tool calls, eliminating the need for separate structured response nodes.
 
         pre_model_hook: An optional node to add before the `agent` node
             (i.e., the node that calls the LLM).

libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py

@@ -79,7 +79,7 @@ def test_configurable() -> None:
 
     Example:
 
-    .. python::
+    .. code-block:: python
 
         # This creates a configurable model without specifying which model
         model = init_chat_model()
@@ -88,10 +88,7 @@ def test_configurable() -> None:
         model.get_num_tokens("hello")  # AttributeError!
 
         # This works - provides model at runtime
-        response = model.invoke(
-            "Hello",
-            config={"configurable": {"model": "gpt-4o"}}
-        )
+        response = model.invoke("Hello", config={"configurable": {"model": "gpt-4o"}})
 
     """
     model = init_chat_model()
@@ -208,7 +205,7 @@ def test_configurable_with_default() -> None:
 
     Example:
 
-    .. python::
+    .. code-block:: python
 
         # This creates a configurable model with default parameters (model)
         model = init_chat_model("gpt-4o", configurable_fields="any", config_prefix="bar")
@@ -218,8 +215,7 @@ def test_configurable_with_default() -> None:
 
         # This also works - switches to Claude at runtime
         response = model.invoke(
-            "Hello",
-            config={"configurable": {"my_model_model": "claude-3-sonnet-20240229"}}
+            "Hello", config={"configurable": {"my_model_model": "claude-3-sonnet-20240229"}}
         )
 
     """

libs/partners/anthropic/langchain_anthropic/chat_models.py

@@ -1185,7 +1185,7 @@ class ChatAnthropic(BaseChatModel):
             print(response.tool_calls)
             print(f'Total tokens: {response.usage_metadata["total_tokens"]}')
 
-        .. code-block:: none
+        .. code-block::
 
             [{'name': 'get_weather', 'args': {'location': 'San Francisco'}, 'id': 'toolu_01HLjQMSb1nWmgevQUtEyz17', 'type': 'tool_call'}]
 
@@ -1295,7 +1295,7 @@ class ChatAnthropic(BaseChatModel):
                 print(response.text())
                 response.tool_calls
 
-            .. code-block:: none
+            .. code-block::
 
                 I'd be happy to help you fix the syntax error in your primes.py file. First, let's look at the current content of the file to identify the error.
 
@@ -2247,7 +2247,7 @@ class ChatAnthropic(BaseChatModel):
                 ]
                 llm.get_num_tokens_from_messages(messages)
 
-            .. code-block:: none
+            .. code-block::
 
                 14
 
@@ -2275,7 +2275,7 @@ class ChatAnthropic(BaseChatModel):
                 ]
                 llm.get_num_tokens_from_messages(messages, tools=[get_weather])
 
-            .. code-block:: none
+            .. code-block::
 
                 403
 

libs/partners/ollama/langchain_ollama/llms.py

@@ -87,7 +87,7 @@ class OllamaLLM(BaseLLM):
             response = llm.invoke(input_text)
             print(response)
 
-        .. code-block:: none
+        .. code-block::
 
             "a philosophical question that has been contemplated by humans for
             centuries..."
@@ -98,7 +98,7 @@ class OllamaLLM(BaseLLM):
             for chunk in llm.stream(input_text):
                 print(chunk, end="")
 
-        .. code-block:: none
+        .. code-block::
 
             a philosophical question that has been contemplated by humans for
             centuries...

libs/partners/openai/langchain_openai/chat_models/azure.py

@@ -868,9 +868,9 @@ class AzureChatOpenAI(BaseChatOpenAI):
                 If schema is specified via TypedDict or JSON schema, ``strict`` is not
                 enabled by default. Pass ``strict=True`` to enable it.
 
-                .. note:
-                    ``strict`` can only be non-null if ``method`` is
-                    ``'json_schema'`` or ``'function_calling'``.
+                .. note::
+                    ``strict`` can only be non-null if ``method`` is ``'json_schema'``
+                    or ``'function_calling'``.
             tools:
                 A list of tool-like objects to bind to the chat model. Requires that:
 

libs/partners/openai/langchain_openai/chat_models/base.py

@@ -2491,7 +2491,7 @@ class ChatOpenAI(BaseChatOpenAI):  # type: ignore[override]
                     for summary in block["summary"]:
                         print(summary["text"])
 
-        .. code-block:: none
+        .. code-block::
 
             Output: 3³ = 27
             Reasoning: The user wants to know...
@@ -2787,7 +2787,6 @@ class ChatOpenAI(BaseChatOpenAI):  # type: ignore[override]
         - ``extra_body``: Parameters are **nested under ``extra_body``** key in request
 
         .. important::
-
             Always use ``extra_body`` for custom parameters, **not** ``model_kwargs``.
             Using ``model_kwargs`` for non-OpenAI parameters will cause API errors.
 

libs/partners/openai/langchain_openai/llms/base.py

@@ -129,7 +129,7 @@ class BaseOpenAI(BaseLLM):
             response = llm.invoke(input_text)
             print(response)
 
-        .. code-block:: none
+        .. code-block::
 
             "a philosophical question that has been debated by thinkers and
             scholars for centuries."
@@ -140,7 +140,7 @@ class BaseOpenAI(BaseLLM):
             for chunk in llm.stream(input_text):
                 print(chunk, end="")
 
-        .. code-block:: none
+        .. code-block::
 
             a philosophical question that has been debated by thinkers and
             scholars for centuries.
@@ -157,7 +157,7 @@ class BaseOpenAI(BaseLLM):
             # batch:
             # await llm.abatch([input_text])
 
-        .. code-block:: none
+        .. code-block::
 
             "a philosophical question that has been debated by thinkers and
             scholars for centuries."
@@ -754,7 +754,7 @@ class OpenAI(BaseOpenAI):
             input_text = "The meaning of life is "
             llm.invoke(input_text)
 
-        .. code-block:: none
+        .. code-block::
 
             "a philosophical question that has been debated by thinkers and scholars for centuries."
 
@@ -764,7 +764,7 @@ class OpenAI(BaseOpenAI):
             for chunk in llm.stream(input_text):
                 print(chunk, end="|")
 
-        .. code-block:: none
+        .. code-block::
 
             a| philosophical| question| that| has| been| debated| by| thinkers| and| scholars| for| centuries|.
 
@@ -772,7 +772,7 @@ class OpenAI(BaseOpenAI):
 
             "".join(llm.stream(input_text))
 
-        .. code-block:: none
+        .. code-block::
 
             "a philosophical question that has been debated by thinkers and scholars for centuries."
 
@@ -788,7 +788,7 @@ class OpenAI(BaseOpenAI):
             # batch:
             # await llm.abatch([input_text])
 
-        .. code-block:: none
+        .. code-block::
 
             "a philosophical question that has been debated by thinkers and scholars for centuries."
 

libs/standard-tests/langchain_tests/integration_tests/chat_models.py

@@ -219,12 +219,13 @@ class ChatModelIntegrationTests(ChatModelTests):
 
         Value to use for tool choice when used in tests.
 
-        .. warning:: Deprecated since version 0.3.15:
-           This property will be removed in version 0.3.20. If a model supports
-           ``tool_choice``, it should accept ``tool_choice="any"`` and
-           ``tool_choice=<string name of tool>``. If a model does not
-           support forcing tool calling, override the ``has_tool_choice`` property to
-           return ``False``.
+        .. warning::
+            Deprecated since version 0.3.15.
+            This property will be removed in version 0.3.20. If a model supports
+            ``tool_choice``, it should accept ``tool_choice="any"`` and
+            ``tool_choice=<string name of tool>``. If a model does not
+            support forcing tool calling, override the ``has_tool_choice`` property to
+            return ``False``.
 
         Example:
 
@@ -2990,7 +2991,6 @@ class ChatModelIntegrationTests(ChatModelTests):
                     return False
 
             .. important::
-
                 VCR will by default record authentication headers and other sensitive
                 information in cassettes. See ``enable_vcr_tests`` dropdown
                 :class:`above <ChatModelIntegrationTests>` for how to configure what

libs/standard-tests/langchain_tests/unit_tests/chat_models.py

@@ -344,11 +344,12 @@ class ChatModelUnitTests(ChatModelTests):
 
         Value to use for tool choice when used in tests.
 
-        .. warning:: Deprecated since version 0.3.15:
-           This property will be removed in version 0.3.20. If a model does not
-           support forcing tool calling, override the ``has_tool_choice`` property to
-           return ``False``. Otherwise, models should accept values of ``'any'`` or
-           the name of a tool in ``tool_choice``.
+        .. warning::
+            Deprecated since version 0.3.15.
+            This property will be removed in version 0.3.20. If a model does not
+            support forcing tool calling, override the ``has_tool_choice`` property to
+            return ``False``. Otherwise, models should accept values of ``'any'`` or
+            the name of a tool in ``tool_choice``.
 
         Example: