diff --git a/.cursorrules b/.cursorrules index 58649c3f4..f9ea4a56d 100644 --- a/.cursorrules +++ b/.cursorrules @@ -1,6 +1,6 @@ # LangChain Documentation Guidelines -Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored docs only—not `**/reference/**` directories or build artifacts. +Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored content under `src/`—not Mintlify `build/` output. For full guidelines, see `CLAUDE.md` in the repository root. @@ -8,7 +8,7 @@ For full guidelines, see `CLAUDE.md` in the repository root. 1. **Always ask for clarification** rather than making assumptions 2. **Never use markdown in frontmatter `description`** — breaks SEO -3. **Never edit `reference/` directory** — auto-generated +3. **Never edit `build/`** — Mintlify build output (regenerate with `make build` or `make dev`) 4. **Always update `src/docs.json`** when adding new pages 5. **Use Tabler icons only** — not FontAwesome 6. **Test code examples** before including them @@ -30,14 +30,14 @@ docs/ │ │ ├── javascript/ # TypeScript-specific (integrations, migrations, releases) │ │ ├── integrations/ # Shared integration content │ │ ├── concepts/ # Conceptual overviews -│ │ └── contributing/ # Contribution guides +│ │ ├── contributing/ # Contribution guides +│ │ └── reference/ # Reference tab entry pages (link to reference.langchain.com) │ ├── snippets/ # Reusable MDX snippets │ ├── images/ # Documentation images │ │ ├── brand/ # Logos, favicons │ │ └── providers/ # Provider icons (dark/ and light/ variants) │ └── fonts/ # Font files ├── pipeline/ # Python build system & preprocessors -├── reference/ # Auto-generated API reference — do not edit ├── build/ # Build output — do not edit ├── scripts/ # Helper utilities └── tests/ # Pipeline tests @@ -76,7 +76,7 @@ Flat groups (no tabs): Get started, Tools and integrations, Advanced, Additional | LangGraph | `src/oss/langgraph/` | | Integrations | `src/oss/python/integrations/` or `src/oss/javascript/integrations/` | | Learn | `src/oss/` (various) | -| Reference | `reference/` — auto-generated, do not edit | +| Reference | `src/oss/reference/` — short entry pages linking to reference.langchain.com | | Contribute | `src/oss/contributing/` | ## Quick reference diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 041c7ff00..9717a165c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,15 +1,15 @@ # LangChain Documentation Guidelines -Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored docs only—not `**/reference/**` directories or build artifacts. +Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored content under `src/`—not Mintlify `build/` output. ## Critical rules 1. **Always ask for clarification** rather than making assumptions -2. **Never use markdown in frontmatter `description`** — breaks SEO -3. **Never edit `reference/` directory** — auto-generated -4. **Always update `src/docs.json`** when adding new pages -5. **Use Tabler icons only** — not FontAwesome -6. **Test code examples** before including them +1. **Never use markdown in frontmatter `description`** — breaks SEO +1. **Never edit `build/`** — Mintlify build output (regenerate with `make build` or `make dev`) +1. **Always update `src/docs.json`** when adding new pages +1. **Use Tabler icons only** — not FontAwesome +1. **Test code examples** before including them ## Repository structure @@ -28,14 +28,14 @@ docs/ │ │ ├── javascript/ # TypeScript-specific (integrations, migrations, releases) │ │ ├── integrations/ # Shared integration content │ │ ├── concepts/ # Conceptual overviews -│ │ └── contributing/ # Contribution guides +│ │ ├── contributing/ # Contribution guides +│ │ └── reference/ # Reference tab entry pages (link to reference.langchain.com) │ ├── snippets/ # Reusable MDX snippets │ ├── images/ # Documentation images │ │ ├── brand/ # Logos, favicons │ │ └── providers/ # Provider icons (dark/ and light/ variants) │ └── fonts/ # Font files ├── pipeline/ # Python build system & preprocessors -├── reference/ # Auto-generated API reference — do not edit ├── build/ # Build output — do not edit ├── scripts/ # Helper utilities └── tests/ # Pipeline tests @@ -74,7 +74,7 @@ Flat groups (no tabs): Get started, Tools and integrations, Advanced, Additional | LangGraph | `src/oss/langgraph/` | | Integrations | `src/oss/python/integrations/` or `src/oss/javascript/integrations/` | | Learn | `src/oss/` (various) | -| Reference | `reference/` — auto-generated, do not edit | +| Reference | `src/oss/reference/` — short entry pages linking to reference.langchain.com | | Contribute | `src/oss/contributing/` | ## Quick reference diff --git a/.github/labeler.yml b/.github/labeler.yml index a55598d41..e36ddf507 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -65,29 +65,13 @@ labels: - '**/*.js' - '**/*.ts' - # Label for reference-specific documentation + # Label for OSS Reference tab entry pages (links to reference.langchain.com) - label: reference sync: true matcher: files: any: - - 'reference/**' - - # Label for Python reference-specific documentation - - label: python-reference - sync: true - matcher: - files: - any: - - 'reference/python/**' - - # Label for JS reference-specific documentation - - label: javascript-reference - sync: true - matcher: - files: - any: - - 'reference/javascript/**' + - 'src/oss/reference/**' # Label for build/CI changes - label: ci diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index 2374e54f0..000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "reference/external/html-docs"] - path = reference/external/html-docs - url = https://github.com/langchain-ai/langchain-api-docs-html.git diff --git a/AGENTS.md b/AGENTS.md index 4e14468cf..b73d8ea64 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,14 +2,14 @@ # LangChain Documentation Guidelines -Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored docs only—not `**/reference/**` directories or build artifacts. +Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored content under `src/`—not Mintlify `build/` output. ## Critical rules 1. **Always ask for clarification** rather than making assumptions 2. **Never fabricate** examples, JSON snippets, policy details, or use case descriptions — use only content from the user or existing source files 3. **Never use markdown in frontmatter `description`** — breaks SEO -4. **Never edit `reference/` directory** — auto-generated +4. **Never edit `build/`** — Mintlify build output (regenerate with `make build` or `make dev`) 5. **Always update `src/docs.json`** when adding new pages 6. **Use Tabler icons only** — not FontAwesome 7. **Test code examples** before including them @@ -29,6 +29,7 @@ Documentation for LangChain products hosted on Mintlify. These guidelines apply | Build system | `pipeline/` | | Icon library | Tabler — | | Mintlify components | | +| API reference site | [reference.langchain.com](https://reference.langchain.com/python/) — built outside this repo; [report issues here](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml) | | Mintlify MCP server | `npx add-mcp https://www.mintlify.com/docs/mcp` | ## Project structure @@ -50,7 +51,8 @@ docs/ │ │ ├── javascript/ # TypeScript-specific (integrations, migrations, releases) │ │ ├── integrations/ # Shared integration content │ │ ├── concepts/ # Conceptual overviews -│ │ └── contributing/ # Contribution guides +│ │ ├── contributing/ # Contribution guides +│ │ └── reference/ # Reference tab entry pages (link to reference.langchain.com) │ ├── snippets/ # Reusable MDX snippets │ │ ├── langsmith/ # LangSmith snippets │ │ ├── oss/ # OSS snippets @@ -110,7 +112,7 @@ Flat groups (no tabs): | LangGraph | `src/oss/langgraph/` | Get started, Capabilities, Production, Frontend, LangGraph APIs | | Integrations* | `src/oss/python/integrations/` or `src/oss/javascript/integrations/` | Popular Providers, Integrations by component (TS: "General integrations, RAG integrations") | | Learn* | `src/oss/` (various) | Tutorials, Conceptual overviews, Additional resources (TS adds: "LangChain Academy") | -| Reference | `src/oss/reference/` | Reference, Errors, Releases, Policies — auto-generated, do not edit | +| Reference | `src/oss/reference/` | Reference, Errors, Releases, Policies — short entry pages linking to reference.langchain.com | | Contribute | `src/oss/contributing/` | Contribution guides, integration authoring | ## Local development diff --git a/CLAUDE.md b/CLAUDE.md index 4e14468cf..b73d8ea64 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,14 +2,14 @@ # LangChain Documentation Guidelines -Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored docs only—not `**/reference/**` directories or build artifacts. +Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored content under `src/`—not Mintlify `build/` output. ## Critical rules 1. **Always ask for clarification** rather than making assumptions 2. **Never fabricate** examples, JSON snippets, policy details, or use case descriptions — use only content from the user or existing source files 3. **Never use markdown in frontmatter `description`** — breaks SEO -4. **Never edit `reference/` directory** — auto-generated +4. **Never edit `build/`** — Mintlify build output (regenerate with `make build` or `make dev`) 5. **Always update `src/docs.json`** when adding new pages 6. **Use Tabler icons only** — not FontAwesome 7. **Test code examples** before including them @@ -29,6 +29,7 @@ Documentation for LangChain products hosted on Mintlify. These guidelines apply | Build system | `pipeline/` | | Icon library | Tabler — | | Mintlify components | | +| API reference site | [reference.langchain.com](https://reference.langchain.com/python/) — built outside this repo; [report issues here](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml) | | Mintlify MCP server | `npx add-mcp https://www.mintlify.com/docs/mcp` | ## Project structure @@ -50,7 +51,8 @@ docs/ │ │ ├── javascript/ # TypeScript-specific (integrations, migrations, releases) │ │ ├── integrations/ # Shared integration content │ │ ├── concepts/ # Conceptual overviews -│ │ └── contributing/ # Contribution guides +│ │ ├── contributing/ # Contribution guides +│ │ └── reference/ # Reference tab entry pages (link to reference.langchain.com) │ ├── snippets/ # Reusable MDX snippets │ │ ├── langsmith/ # LangSmith snippets │ │ ├── oss/ # OSS snippets @@ -110,7 +112,7 @@ Flat groups (no tabs): | LangGraph | `src/oss/langgraph/` | Get started, Capabilities, Production, Frontend, LangGraph APIs | | Integrations* | `src/oss/python/integrations/` or `src/oss/javascript/integrations/` | Popular Providers, Integrations by component (TS: "General integrations, RAG integrations") | | Learn* | `src/oss/` (various) | Tutorials, Conceptual overviews, Additional resources (TS adds: "LangChain Academy") | -| Reference | `src/oss/reference/` | Reference, Errors, Releases, Policies — auto-generated, do not edit | +| Reference | `src/oss/reference/` | Reference, Errors, Releases, Policies — short entry pages linking to reference.langchain.com | | Contribute | `src/oss/contributing/` | Contribution guides, integration authoring | ## Local development diff --git a/README.md b/README.md index cb0158913..f3796fb9e 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 🦜 **Welcome!** This repository contains the documentation build pipeline for LangChain projects. * 🏠 [`docs.langchain.com`](https://docs.langchain.com) is our docs home, centralizing LangChain, LangGraph, LangSmith, and LangChain Labs (Deep Agents, Open SWE, Open Agent Platform). This site is hosted on [Mintlify](https://mintlify.com). -* 🛠️ `reference.langchain.com` is home to the API reference docs for LangChain, LangGraph, LangSmith, and LangChain integration packages (e.g., [`langchain-anthropic`](https://pypi.org/project/langchain-anthropic/), [`langchain-openai`](https://pypi.org/project/langchain-openai/)). These are static sites built from the source code and deployed to [Vercel](https://vercel.com). +* 🛠️ [`reference.langchain.com`](https://reference.langchain.com/python/) hosts generated API reference for LangChain, LangGraph, LangSmith, and integration packages. That site is **not** built from this repository (no reference build scripts or output live here). * [`Python reference`](https://reference.langchain.com/python/) * [`JavaScript/TypeScript reference`](https://reference.langchain.com/javascript/) * 💬 [`chat.langchain.com`](https://chat.langchain.com) is an AI-powered assistant that can answer questions about LangChain documentation. @@ -52,8 +52,7 @@ For more information on how to contribute to LangChain documentation, follow the For detailed information about setting up your development environment and contributing to documentation, see the [documentation contributing guide](https://docs.langchain.com/oss/python/contributing/documentation). -> [!IMPORTANT] -> For contributing to reference docs, see the `README.md` file in the `/reference/python` and `/reference/javascript` directories. +To report issues with **reference.langchain.com** (missing pages, broken links, or generated API content), [open a reference documentation issue](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml) on this repo so maintainers can route it. ## Reference @@ -62,6 +61,7 @@ For detailed information about setting up your development environment and contr ```text # --- docs.langchain.com ---------------------------------------------- build/ # Built docs (DO NOT EDIT) +packages.yml # Package metadata (indexes, tables, downloads; not the API reference build) pipeline/ # Build pipeline source code scripts/ # Helper scripts src/ # Source documentation files (< EDIT CONTENT HERE) @@ -71,14 +71,6 @@ src/ # Source documentation files (< EDIT CONTENT HERE) tests/ # Test files for the pipeline Makefile # Build targets pyproject.toml # Dependencies - -# --- reference.langchain.com ----------------------------------------- -reference/ # Reference docs build pipelines - dist/ # Built docs (DO NOT EDIT) - javascript/ # JS/TS reference build pipeline - python/ # Python reference build pipeline and source - package.json # Vercel commands and dependencies - vercel.json # Vercel configuration/redirects ``` #### `docs.langchain.com` @@ -94,9 +86,7 @@ Documentation changes follow a PR workflow where all tests must pass before merg #### `reference.langchain.com` -Each language has its own build pipeline in `/reference/`. Reference docs are built with a combination of automated docstring extraction and manually written content. Refer to the `README.md` in each folder for details on how to build and contribute. - -Built files are stored in `/reference/dist/{LANGUAGE}`, which is then deployed to Vercel. The build process is triggered automatically on pushes to `main` and can also be triggered manually via the Vercel dashboard. +API reference is generated and deployed outside this repo. Browse [Python](https://reference.langchain.com/python/) and [JavaScript/TypeScript](https://reference.langchain.com/javascript/) reference there. If something is wrong with that site, use the [reference docs issue template](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml). ### File formats @@ -113,8 +103,6 @@ Built files are stored in `/reference/dist/{LANGUAGE}`, which is then deployed t * `make build` - Build documentation to `./build` directory * `make broken-links` - Check for broken links in documentation * `make broken-links-with-anchors` - Check for broken links + check links with anchors -* `make build-references` - Build reference docs -* `make preview-references` - Preview reference docs using vercel * `make install` - Install all dependencies * `make clean` - Remove build artifacts * `make test` - Run the test suite diff --git a/pyproject.toml b/pyproject.toml index 19e3d2a19..743e281a5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -114,10 +114,6 @@ ignore = [ "D103", # Missing docstring in simple function ] -"reference/python/**/*.py" = [ - "T201", # Print statements -] - "pipeline/preprocessors/link_map.py" = [ "E501", # Line length ] diff --git a/src/oss/contributing/documentation.mdx b/src/oss/contributing/documentation.mdx index af638adc8..cdefd3882 100644 --- a/src/oss/contributing/documentation.mdx +++ b/src/oss/contributing/documentation.mdx @@ -206,12 +206,7 @@ A good reference should: - :::python - See the contributing guide for [Python reference docs](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md). - ::: - :::js - See the contributing guide for [JavaScript/TypeScript reference docs](https://github.com/langchain-ai/docs/blob/main/reference/javascript/README.md). - ::: + The generated API reference at [reference.langchain.com](https://reference.langchain.com/python/) is built and deployed outside this repository. To report bugs, missing packages, or broken pages there, [open a reference documentation issue](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml). @@ -258,12 +253,7 @@ Tutorials are longer form step-by-step guides that builds upon itself and takes ## Writing standards - :::python - Reference documentation has different standards - see the [reference docs contributing guide](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md) for details. - ::: - :::js - Reference documentation has different standards - see the [reference docs contributing guide](https://github.com/langchain-ai/docs/blob/main/reference/javascript/README.md) for details. - ::: + Standards for pages on [reference.langchain.com](https://reference.langchain.com/python/) live with that site’s build pipeline, not in this repo. Use the [reference documentation issue template](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml) for questions or fixes about generated API reference content. ### Mintlify components @@ -411,7 +401,7 @@ If a link isn't found in the map, it will be left unchanged in the output. To ad :::python **From API reference stubs to OSS docs:** -See the [`README`](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md) for more information on linking from API reference stubs to Python OSS docs. Specifically see the `mkdocstrings` cross-reference [linking syntax](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md#mkdocsmkdocstrings-python-cross-reference-linking-syntax). +Cross-links and deep anchors in the published Python API reference are generated outside this repository. If a link from reference.langchain.com to docs.langchain.com is wrong or outdated, [open an issue](https://github.com/langchain-ai/docs/issues/new?template=04-reference-docs.yml) with the source and destination URLs. ::: ### Localization