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

mdrxy · web-flow · commit 5bea28393df0 · 2025-09-25T16:49:56.000-04:00
and fix typos
diff --git a/docs/api_reference/_extensions/gallery_directive.py b/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.
     """
 
diff --git a/docs/api_reference/conf.py b/docs/api_reference/conf.py
@@ -126,7 +126,7 @@ def skip_private_members(app, what, name, obj, skip, options):
     "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 @@ def skip_private_members(app, what, name, obj, skip, options):
 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
diff --git a/docs/api_reference/requirements.txt b/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
diff --git a/libs/cli/langchain_cli/integration_template/integration_template/retrievers.py b/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 @@ def format_docs(docs):
 
             chain.invoke("...")
 
-        .. code-block:: none
+        .. code-block::
 
              # TODO: Example output.
 
diff --git a/libs/cli/langchain_cli/integration_template/integration_template/toolkits.py b/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.
 
diff --git a/libs/core/langchain_core/callbacks/manager.py b/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.
 
diff --git a/libs/core/langchain_core/callbacks/usage.py b/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,
diff --git a/libs/core/langchain_core/document_loaders/langsmith.py b/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": {...}, ...}), ...]
 
diff --git a/libs/core/langchain_core/indexing/api.py b/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.
-
-    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.
+    are not able to specify the uid of the document.
+
+    .. 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.
diff --git a/libs/core/langchain_core/runnables/graph_ascii.py b/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 |
diff --git a/libs/core/langchain_core/utils/aiter.py b/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)
diff --git a/libs/core/langchain_core/utils/iter.py b/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)
diff --git a/libs/core/langchain_core/vectorstores/in_memory.py b/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 @@ def _filter_function(doc: Document) -> bool:
             for doc in results:
                 print(f"* {doc.page_content} [{doc.metadata}]")
 
-        .. code-block:: none
+        .. code-block::
 
             * thud [{'bar': 'baz'}]
 
@@ -123,7 +123,7 @@ def _filter_function(doc: Document) -> bool:
             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 @@ def _filter_function(doc: Document) -> bool:
             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 @@ def _filter_function(doc: Document) -> bool:
             )
             retriever.invoke("thud")
 
-        .. code-block:: none
+        .. code-block::
 
             [Document(id='2', metadata={'bar': 'baz'}, page_content='thud')]
 
diff --git a/libs/langchain/langchain/chains/llm_math/base.py b/libs/langchain/langchain/chains/llm_math/base.py
@@ -123,7 +123,7 @@ async def acall_model(state: ChainState, config: RunnableConfig):
             async for event in events:
                 event["messages"][-1].pretty_print()
 
-        .. code-block:: none
+        .. code-block::
 
             ================================ Human Message =================================
 
diff --git a/libs/langchain/tests/unit_tests/chat_models/test_base.py b/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,21 +205,23 @@ 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")
 
         # 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",
diff --git a/libs/langchain_v1/langchain/agents/react_agent.py b/libs/langchain_v1/langchain/agents/react_agent.py
@@ -985,10 +985,10 @@ def select_model(state: AgentState, runtime: Runtime[ModelContext]) -> ChatOpenA
               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 select_model(state: AgentState, runtime: Runtime[ModelContext]) -> ChatOpenA
 
                 - 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 select_model(state: AgentState, runtime: Runtime[ModelContext]) -> ChatOpenA
                 `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).
diff --git a/libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py b/libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py
diff --git a/libs/partners/anthropic/langchain_anthropic/chat_models.py b/libs/partners/anthropic/langchain_anthropic/chat_models.py
diff --git a/libs/partners/ollama/langchain_ollama/llms.py b/libs/partners/ollama/langchain_ollama/llms.py
diff --git a/libs/partners/openai/langchain_openai/chat_models/azure.py b/libs/partners/openai/langchain_openai/chat_models/azure.py
diff --git a/libs/partners/openai/langchain_openai/chat_models/base.py b/libs/partners/openai/langchain_openai/chat_models/base.py
diff --git a/libs/partners/openai/langchain_openai/llms/base.py b/libs/partners/openai/langchain_openai/llms/base.py
diff --git a/libs/standard-tests/langchain_tests/integration_tests/chat_models.py b/libs/standard-tests/langchain_tests/integration_tests/chat_models.py
diff --git a/libs/standard-tests/langchain_tests/unit_tests/chat_models.py b/libs/standard-tests/langchain_tests/unit_tests/chat_models.py
