more refs!

pipeline/preprocessors/handle_auto_links.py

@@ -104,11 +104,15 @@ def _transform_link(
         (?P<title>[^\]]+)   # Custom title - one or more non-bracket characters
         \]                  # Closing bracket for title
         \[                  # Opening bracket for link name
-        (?P<link_name_with_title>[^\]]+)  # Link name - non-bracket chars
+        (?P<backtick_with_title>`)?  # Optional backtick before link name
+        (?P<link_name_with_title>[^`\]]+)  # Link name - non-backtick/bracket chars
+        (?(backtick_with_title)`|)  # Closing backtick if opening backtick present
         \]                  # Closing bracket for link name
         |                   # OR
         @\[                 # @ symbol followed by opening bracket
-        (?P<link_name>[^\]]+)   # Link name - one or more non-bracket characters
+        (?P<backtick>`)?    # Optional backtick before link name
+        (?P<link_name>[^`\]]+)   # Link name - non-backtick/bracket characters
+        (?(backtick)`|)     # Closing backtick if opening backtick present
         \]                  # Closing bracket
     )
     """,
@@ -128,12 +132,18 @@ def replace_cross_reference(match: re.Match[str]) -> str:
         if title is not None:
             # This is @[title][ref] format
             link_name = match.group("link_name_with_title")
+            has_backticks = match.group("backtick_with_title") is not None
             custom_title = title
         else:
             # This is @[ref] format
             link_name = match.group("link_name")
+            has_backticks = match.group("backtick") is not None
             custom_title = None
 
+        # If no custom title and backticks are present, add them to the title
+        if custom_title is None and has_backticks:
+            custom_title = f"`{link_name}`"
+
         transformed = _transform_link(
             link_name, scope, file_path, line_number, custom_title
         )

pipeline/preprocessors/link_map.py

@@ -130,26 +130,6 @@ class LinkMap(TypedDict):
             "update_state": "reference/classes/langgraph.CompiledStateGraph.html#updateState",
         },
     },
-    {
-        # Python LangChain reference
-        "host": "https://python.langchain.com/api_reference/",
-        "scope": "python",
-        "links": {
-            "AIMessage": "core/messages/langchain_core.messages.ai.AIMessage.html",
-            "AIMessageChunk": "core/messages/langchain_core.messages.ai.AIMessageChunk.html",
-            "BaseChatModel.invoke": "core/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel.invoke",
-            "BaseChatModel.stream": "core/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel.stream",
-            "BaseChatModel.astream_events": "core/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel.astream_events",
-            "BaseChatModel.batch": "core/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel.batch",
-            "BaseChatModel.batch_as_completed": "core/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel.batch_as_completed",
-            "BaseChatModel.bind_tools": "core/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel.bind_tools",
-            "Document": "core/documents/langchain_core.documents.base.Document.html",
-            "init_chat_model": "langchain/chat_models/langchain.chat_models.base.init_chat_model.html",
-            "RunnableConfig": "core/runnables/langchain_core.runnables.config.RunnableConfig.html",
-            "@tool": "core/tools/langchain_core.tools.convert.tool.html",
-            "Embeddings": "core/embeddings/langchain_core.embeddings.embeddings.Embeddings.html",
-        },
-    },
     {
         "host": "https://v03.api.js.langchain.com/",
         "scope": "js",
@@ -172,9 +152,73 @@ class LinkMap(TypedDict):
         "host": "https://reference.langchain.com/python/",
         "scope": "python",
         "links": {
+            # Module pages
+            "langchain": "langchain/langchain",
+            "langchain.agents": "langchain/agents",
+            "langchain.messages": "langchain/messages",
+            "langchain.tools": "langchain/tools",
+            "langchain.chat_models": "langchain/models",
+            "langchain.embeddings": "langchain/embeddings",
+            "langchain_core": "langchain_core/",
+            # Agents
+            "create_agent": "langchain/agents/#langchain.agents.create_agent",
+            "create_agent(tools)": "langchain/agents/#langchain.agents.create_agent(tools)",
+            "system_prompt": "langchain/agents/#langchain.agents.create_agent(system_prompt)",
+            "AgentState": "langchain/agents/#langchain.agents.AgentState",
+            # Middleware
+            "AgentMiddleware": "langchain/middleware/#langchain.agents.middleware.AgentMiddleware",
+            "state_schema": "langchain/middleware/#langchain.agents.middleware.AgentMiddleware.state_schema",
+            "PIIMiddleware": "langchain/middleware/#langchain.agents.middleware.PIIMiddleware",
+            "SummarizationMiddleware": "langchain/middleware/#langchain.agents.middleware.SummarizationMiddleware",
+            "HumanInTheLoopMiddleware": "langchain/middleware/#langchain.agents.middleware.HumanInTheLoopMiddleware",
+            # Messages
+            "AIMessage": "langchain/messages/#langchain.messages.AIMessage",
+            "AIMessageChunk": "langchain/messages/#langchain.messages.AIMessageChunk",
+            "ToolMessage": "langchain/messages/#langchain.messages.ToolMessage",
+            "SystemMessage": "langchain/messages/#langchain.messages.SystemMessage",
+            "trim_messages": "langchain/messages/#langchain.messages.trim_messages",
+            # Content blocks
+            "BaseMessage": "langchain_core/language_models/#langchain_core.messages.BaseMessage",
+            "BaseMessage(content)": "langchain_core/language_models/#langchain_core.messages.BaseMessage.content",
+            "BaseMessage(content_blocks)": "langchain_core/language_models/#langchain_core.messages.BaseMessage.content_blocks",
+            "ContentBlock": "langchain/messages/#langchain.messages.ContentBlock",
+            "TextContentBlock": "langchain/messages/#langchain.messages.TextContentBlock",
+            "ReasoningContentBlock": "langchain/messages/#langchain.messages.ReasoningContentBlock",
+            "NonStandardContentBlock": "langchain/messages/#langchain.messages.NonStandardContentBlock",
+            "ImageContentBlock": "langchain/messages/#langchain.messages.ImageContentBlock",
+            "VideoContentBlock": "langchain/messages/#langchain.messages.VideoContentBlock",
+            "AudioContentBlock": "langchain/messages/#langchain.messages.AudioContentBlock",
+            "PlainTextContentBlock": "langchain/messages/#langchain.messages.PlainTextContentBlock",
+            "FileContentBlock": "langchain/messages/#langchain.messages.FileContentBlock",
+            "ToolCall": "langchain/messages/#langchain.messages.ToolCall",
+            "ToolCallChunk": "langchain/messages/#langchain.messages.ToolCallChunk",
+            "ServerToolCall": "langchain/messages/#langchain.messages.ServerToolCall",
+            "ServerToolCallChunk": "langchain/messages/#langchain.messages.ServerToolCallChunk",
+            "ServerToolResult": "langchain/messages/#langchain.messages.ServerToolResult",
+            # Integrations
             "langchain-openai": "integrations/langchain_openai",
             "ChatOpenAI": "integrations/langchain_openai/#langchain_openai.ChatOpenAI",
             "AzureChatOpenAI": "integrations/langchain_openai/#langchain_openai.AzureChatOpenAI",
+            # Models
+            "init_chat_model": "langchain/models/#langchain.chat_models.init_chat_model",
+            "init_chat_model(model_provider)": "langchain/models/#langchain.chat_models.init_chat_model(model_provider)",
+            "BaseChatModel": "langchain_core/language_models/#langchain_core.language_models.chat_models.BaseChatModel",
+            "BaseChatModel.invoke": "langchain_core/language_models/#langchain_core.language_models.chat_models.BaseChatModel.invoke",
+            "BaseChatModel.stream": "langchain_core/language_models/#langchain_core.language_models.chat_models.BaseChatModel.stream",
+            "BaseChatModel.astream_events": "langchain_core/language_models/#langchain_core.language_models.chat_models.BaseChatModel.astream_events",
+            "BaseChatModel.batch": "langchain_core.language_models.chat_models.BaseChatModel.batch",
+            "BaseChatModel.batch_as_completed": "langchain_core.language_models.chat_models.BaseChatModel.batch_as_completed",
+            "BaseChatModel.bind_tools": "langchain_core/language_models/#langchain_core.language_models.chat_models.BaseChatModel.bind_tools",
+            # Tools
+            "@tool": "langchain/tools/#langchain.tools.tool",
+            "BaseTool": "langchain/tools/#langchain.tools.BaseTool",
+            # Embeddings
+            "init_embeddings": "langchain_core/embeddings/#langchain_core.embeddings.embeddings.Embeddings",
+            "Embeddings": "langchain_core/embeddings/#langchain_core.embeddings.embeddings.Embeddings",
+            # Documents
+            "Document": "langchain_core/documents/#langchain_core.documents.base.Document",
+            # Runnables
+            "RunnableConfig": "langchain_core/runnables/#langchain_core.runnables.RunnableConfig",
         },
     },
     {

reference/python/README.md

@@ -158,3 +158,228 @@ The `pyproject.dev.toml` file expects repositories to be cloned in this structur
 
 If you only need to work on specific packages, you can comment out the others in `pyproject.dev.toml`.
 
+---
+
+## MkDocs/mkdocstrings Python Cross-Reference Linking Syntax
+
+### Basic Syntax
+
+The general format for cross-references in mkdocstrings is:
+
+```markdown
+[display text][python.path.to.object]
+```
+
+If you want the object name as the display text, use backticks:
+
+```markdown
+[`object_name`][python.path.to.object]
+```
+
+### Linking to Different Python Objects
+
+#### Modules
+
+```markdown
+[`langchain.agents`][langchain.agents]
+
+# or
+
+[agents module][langchain.agents]
+```
+
+#### Classes
+
+```markdown
+[`ChatOpenAI`][langchain_openai.ChatOpenAI]
+
+# or
+
+[the ChatOpenAI class][langchain_openai.ChatOpenAI]
+```
+
+#### Functions
+
+```markdown
+[`init_chat_model`][langchain.chat_models.init_chat_model]
+
+# or
+
+[initialization function][langchain.chat_models.init_chat_model]
+```
+
+#### Methods
+
+```markdown
+[`invoke`][langchain_openai.ChatOpenAI.invoke]
+
+# or
+
+[the invoke method][langchain_openai.ChatOpenAI.invoke]
+```
+
+#### Class Attributes
+
+```markdown
+[`temperature`][langchain_openai.ChatOpenAI.temperature]
+
+# or
+
+[the temperature attribute][langchain_openai.ChatOpenAI.temperature]
+```
+
+#### Function/Method Parameters
+
+**Note:** Parameter linking requires the `parameter_headings` option to be enabled in the `mkdocstrings` config (in `mkdocs.yml`). This generates permalinks and TOC entries for each parameter, so don't disable it.
+
+Use `(parameter_name)` syntax to link to specific parameters:
+
+```markdown
+[`model_provider`][langchain.chat_models.init_chat_model(model_provider)]
+
+# or
+
+[the model_provider parameter][langchain.chat_models.init_chat_model(model_provider)]
+```
+
+For method parameters:
+
+```markdown
+[`max_tokens`][langchain_openai.ChatOpenAI.invoke(max_tokens)]
+```
+
+For class `__init__` parameters (when using `merge_init_into_class`):
+
+```markdown
+[`temperature`][langchain_openai.ChatOpenAI(temperature)]
+```
+
+For variadic parameters:
+
+```markdown
+[`*args`][package.module.function(*args)]
+[`**kwargs`][package.module.function(**kwargs)]
+```
+
+#### Return Values
+
+Not directly linkable, but you can link to the return type class:
+
+```markdown
+Returns a [`ChatResult`][langchain_core.outputs.ChatResult] object.
+```
+
+#### Nested Classes
+
+```markdown
+[`Config`][langchain_core.runnables.Runnable.Config]
+```
+
+### Advanced Patterns
+
+#### Linking Within Same Module
+
+If you're documenting within the same module, you can use relative paths:
+
+```markdown
+See also [`.other_method`][.other_method]
+```
+
+#### Linking to Exceptions
+
+```markdown
+Raises [`ValueError`][ValueError] if input is invalid.
+Raises [`CustomError`][my_package.exceptions.CustomError]
+```
+
+#### Linking to Type Aliases
+
+```markdown
+[`RunnableConfig`][langchain_core.runnables.config.RunnableConfig]
+```
+
+#### Multiple Links in Args Documentation
+
+```python
+def create_agent(
+    model: BaseChatModel,
+    tools: Sequence[BaseTool],
+) -> AgentExecutor:
+    """
+    Create an agent executor.
+
+    Args:
+        model: A [`BaseChatModel`][langchain_core.language_models.BaseChatModel]
+            instance. You can use [`init_chat_model`][langchain.chat_models.init_chat_model]
+            to initialize from a string identifier (see the
+            [`model_provider`][langchain.chat_models.init_chat_model(model_provider)]
+            parameter for available providers).
+        tools: A sequence of [`BaseTool`][langchain_core.tools.BaseTool] instances.
+            Use the [`@tool`][langchain_core.tools.tool] decorator to create tools.
+
+    Returns:
+        An [`AgentExecutor`][langchain.agents.AgentExecutor] instance.
+    """
+```
+
+### Best Practices
+
+#### 1. Use Backticks for Code Identifiers
+
+```markdown
+✅ [`init_chat_model`][langchain.chat_models.init_chat_model]
+❌ [init_chat_model][langchain.chat_models.init_chat_model]
+```
+
+#### 2. Use Full Paths for Clarity
+
+```markdown
+✅ [`BaseChatModel`][langchain_core.language_models.BaseChatModel]
+❌ [`BaseChatModel`][BaseChatModel]  # May not resolve correctly
+```
+
+#### 3. Link to Public APIs Only
+
+Only link to public, exported APIs that users should interact with. Avoid linking to internal implementation details (e.g., objects prefixed with `_`).
+
+#### 4. Use Descriptive Text for Complex References
+
+```markdown
+✅ See the [`model_provider`][langchain.chat_models.init_chat_model(model_provider)]
+   parameter for available providers.
+❌ See [`model_provider`][langchain.chat_models.init_chat_model(model_provider)].
+```
+
+#### 5. Verify Links Build Correctly
+
+Build and manually check the generated HTML to ensure links resolve correctly.
+
+### Quick Reference Table
+
+| Object Type | Syntax | Example |
+|------------|--------|---------|
+| Module | `[text][module.path]` | ``[`agents`][langchain.agents]`` |
+| Class | `[text][module.Class]` | ``[`ChatOpenAI`][langchain_openai.ChatOpenAI]`` |
+| Function | `[text][module.function]` | ``[`init_chat_model`][langchain.chat_models.init_chat_model]`` |
+| Method | `[text][module.Class.method]` | ``[`invoke`][langchain_openai.ChatOpenAI.invoke]`` |
+| Attribute | `[text][module.Class.attr]` | ``[`temperature`][langchain_openai.ChatOpenAI.temperature]`` |
+| Function Param | `[text][module.function(param)]` | ``[`model_provider`][langchain.chat_models.init_chat_model(model_provider)]`` |
+| Method Param | `[text][module.Class.method(param)]` | ``[`max_tokens`][langchain_openai.ChatOpenAI.invoke(max_tokens)]`` |
+| Class Param | `[text][module.Class(param)]` | ``[`temperature`][langchain_openai.ChatOpenAI(temperature)]`` |
+
+### Testing Links
+
+To test if a link will work:
+
+1. Check the object is in `__init__.py` exports
+2. Verify the import path: `from module.path import Object`
+3. Build docs with `--strict` mode
+4. Check the generated HTML for broken links
+
+```bash
+mkdocs build --strict
+mkdocs serve  # Preview at http://127.0.0.1:8000/
+```
+
+This syntax works with the `mkdocstrings` plugin for MkDocs using the Python handler. Adjust paths according to your package structure and exports.
+

reference/python/docs/index.md

@@ -2,7 +2,9 @@
 title: LangChain Python Reference
 ---
 
-Welcome to the [LangChain](https://langchain.com) Python reference documentation! These pages detail the core interfaces you will use when building applications with LangChain and LangGraph. Each section covers a different part of the ecosystem. Use the navigation header to view documentation for specific packages.
+Welcome to the [LangChain](https://langchain.com) Python reference documentation!
+
+These pages detail the core interfaces you will use when building applications with LangChain and LangGraph. Each section covers a different part of the ecosystem. Use the navigation header to view documentation for specific packages.
 
 !!! warning "Work in progress"
     This site is a work in progress. If you have any suggestions or find any issues, please [open an issue on GitHub](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml).

reference/python/docs/langchain/embeddings.md

@@ -6,5 +6,5 @@
     options:
       group_by_category: false
       members:
-        - init_embedding
+        - init_embeddings
         - Embeddings