x

docs/Makefile

@@ -31,9 +31,11 @@ install-py-deps:
 	$(PYTHON) -m uv pip install -r vercel_requirements.txt
 	$(PYTHON) -m uv pip install --editable $(PARTNER_DEPS_LIST)
 
-generate-files:
+_generate-files-internal:
 	mkdir -p $(INTERMEDIATE_DIR)
-	cp -r $(SOURCE_DIR)/* $(INTERMEDIATE_DIR)
+	rsync -am --delete $(SOURCE_DIR) $(INTERMEDIATE_DIR)
+
+generate-files: _generate-files-internal
 	mkdir -p $(INTERMEDIATE_DIR)/templates
 
 	$(PYTHON) scripts/model_feat_table.py $(INTERMEDIATE_DIR)
@@ -59,13 +61,23 @@ render:
 	$(PYTHON) scripts/notebook_convert.py $(INTERMEDIATE_DIR) $(OUTPUT_NEW_DOCS_DIR)
 
 md-sync:
-	rsync -avm --include="*/" --include="*.mdx" --include="*.md" --include="*.png" --exclude="*" $(INTERMEDIATE_DIR)/ $(OUTPUT_NEW_DOCS_DIR)
+	rsync -am --include="*/" --include="*.mdx" --include="*.md" --include="*.png" --exclude="*" $(INTERMEDIATE_DIR)/ $(OUTPUT_NEW_DOCS_DIR)
 
 generate-references:
 	$(PYTHON) scripts/generate_api_reference_links.py --docs_dir $(OUTPUT_NEW_DOCS_DIR)
 
 build: install-py-deps generate-files copy-infra render md-sync
 
+generate-watch:
+	fswatch $(SOURCE_DIR) | xargs -I{} make _generate-files-internal 
+
+echo:
+	echo "hi"
+	echo x$(SOURCE_PATHS)x
+
+build-watch:
+	fswatch $(INTERMEDIATE_DIR) | grep -E --line-buffered "(?:.md|.mdx|.ipynb)$$" | xargs -I{} make render md-sync copy-infra SOURCE_PATHS={}
+
 vercel-build: install-vercel-deps build generate-references
 	rm -rf docs
 	mv $(OUTPUT_NEW_DOCS_DIR) docs

docs/README.md

@@ -1,3 +1,14 @@
 # LangChain Documentation
 
 For more information on contributing to our documentation, see the [Documentation Contributing Guide](https://python.langchain.com/docs/contributing/documentation)
+
+## Makefile
+
+The included Makefile coordinates all building of the documentation.
+There are 4 main steps to building the documentation:
+
+1. Installing dependencies
+2. Copying and downloading files into `build/intermediate`
+3. Rendering the files from `build/intermediate` to `build/output-new`
+4. Building `build/output-new` in docusaurus
+

docs/docs/contributing/documentation/_category_.yml

@@ -1,2 +0,0 @@
-label: 'Documentation'
-position: 3

docs/docs/contributing/how_to/index.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_class_name: hidden
+---
+# Contributor how-to guides
+
+This section contains guides for contributors to the project. If you're looking to contribute to the project, this is a good place to start.
+
+This content is heavily inspired by scikit-learn's [contributing guide](https://scikit-learn.org/dev/developers/contributing.html).
+
+## Getting started
+
+- How to: create a minimal reproducible example
+- How to: find a package's source code
+- How to: set up the codebase
+- How to: lint and format documentation and code
+- [How to: run tests](./testing.mdx): Learn how to run tests in all of our packages
+- How to: open a pull request
+
+## Contributing documentation
+
+- How to: build the documentation locally
+- How to: edit markdown (.md, .mdx) documentation
+- How to: use code tabs in markdown
+- How to: edit Jupyter notebook (.ipynb) documentation
+- How to: add images to documentation
+
+## Contributing code
+
+- How to: find a bug to fix
+- How to: 
+
+## Old stuff
+- [Documentation](./documentation.mdx): Learn how to contribute to the documentation.
+- [Code](./code.mdx): Learn how to develop in the LangChain codebase.
+- [Integrations](./integrations.mdx): Learn how to contribute to third-party integrations to the LangChain ecosystem.

docs/docs/contributing/how_to/minimal_reproducer.mdx

@@ -0,0 +1,19 @@
+---
+sidebar_label: Minimal Reproducible Examples
+sidebar_position: 0
+---
+
+# How to craft a minimal reproducible example for LangChain
+
+:::info
+This guide is a LangChain-specific adaptation of sklearn's [minimal reproducer guide](https://scikit-learn.org/dev/developers/minimal_reproducer.html).
+:::
+
+Whether submitting a bug report, designing a suite of tests, or simply posting a question in the discussions, being able to craft minimal, reproducible examples (or minimal, workable examples) is the key to communicating effectively and efficiently with the community.
+
+There are very good guidelines on the internet such as this [StackOverflow document](https://stackoverflow.com/help/minimal-reproducible-example) or [this blogpost by Matthew Rocklin](https://matthewrocklin.com/minimal-bug-reports) on crafting Minimal Complete Verifiable Examples (referred below as MCVE). Our goal is not to be repetitive with those references but rather to provide a step-by-step guide on how to narrow down a bug until you have reached the shortest possible code to reproduce it.
+
+The first step before submitting a bug report to LangChain is to read the Issue template. It is already quite informative about the information you will be asked to provide.
+
+## Good practices
+

docs/docs/contributing/index.mdx

@@ -1,54 +1,10 @@
----
-sidebar_position: 0
----
-# Welcome Contributors
+# Contributing guide
 
-Hi there! Thank you for even being interested in contributing to LangChain.
-As an open-source project in a rapidly developing field, we are extremely open to contributions, whether they involve new features, improved infrastructure, better documentation, or bug fixes.
+LangChain is an open-source project written by an amazing community of developers and maintained by the team at [LangChain AI](https://www.langchain.com).
 
-## 🗺️ Guidelines
+There are many ways to contribute to LangChain, and please read this guide to learn how you can most effectively contribute to the project!
 
-### 👩‍💻 Ways to contribute
+For existing contributors, we have a [Contributor Cheat Sheet](./reference/cheat_sheet.mdx) as quick reference.
 
-There are many ways to contribute to LangChain. Here are some common ways people contribute:
+## How to contribute
 
-- [**Documentation**](/docs/contributing/documentation/style_guide): Help improve our docs, including this one!
-- [**Code**](./code.mdx): Help us write code, fix bugs, or improve our infrastructure.
-- [**Integrations**](integrations.mdx): Help us integrate with your favorite vendors and tools.
-- [**Discussions**](https://github.com/langchain-ai/langchain/discussions): Help answer usage questions and discuss issues with users.
-
-### 🚩 GitHub Issues
-
-Our [issues](https://github.com/langchain-ai/langchain/issues) page is kept up to date with bugs, improvements, and feature requests.
-
-There is a taxonomy of labels to help with sorting and discovery of issues of interest. Please use these to help organize issues.
-
-If you start working on an issue, please assign it to yourself.
-
-If you are adding an issue, please try to keep it focused on a single, modular bug/improvement/feature.
-If two issues are related, or blocking, please link them rather than combining them.
-
-We will try to keep these issues as up-to-date as possible, though
-with the rapid rate of development in this field some may get out of date.
-If you notice this happening, please let us know.
-
-### 💭 GitHub Discussions
-
-We have a [discussions](https://github.com/langchain-ai/langchain/discussions) page where users can ask usage questions, discuss design decisions, and propose new features.
-
-If you are able to help answer questions, please do so! This will allow the maintainers to spend more time focused on development and bug fixing.
-
-### 🙋 Getting Help
-
-Our goal is to have the simplest developer setup possible. Should you experience any difficulty getting setup, please
-contact a maintainer! Not only do we want to help get you unblocked, but we also want to make sure that the process is
-smooth for future contributors.
-
-In a similar vein, we do enforce certain linting, formatting, and documentation standards in the codebase.
-If you are finding these difficult (or even just annoying) to work with, feel free to contact a maintainer for help -
-we do not want these to get in the way of getting good code into the codebase.
-
-# 🌟 Recognition
-
-If your contribution has made its way into a release, we will want to give you credit on Twitter (only if you want though)!
-If you have a Twitter account you would like us to mention, please let us know in the PR or through another means.

docs/docs/contributing/reference/cheat_sheet.mdx

@@ -0,0 +1,16 @@
+---
+sidebar_label: "Cheat sheet"
+sidebar_position: 1
+---
+# Contributing cheat sheet
+
+## Pull request lifecycle
+
+1. Open a **draft** pull request
+2. Merge in latest master ("Update branch")
+3. Confirm that the CI checks pass
+4. Mark "Ready to review" to convert from draft to full PR
+5. Wait for a review. 
+6. Address review comments within 72 hours. In the event of no activity for 72 hours, the PR will be closed (but you can reopen).
+
+## 

docs/docs/contributing/reference/index.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_class_name: hidden
+---
+# Contributor reference
+
+This section contains reference material for contributors to the project.
+
+- [Cheat sheet](./cheat_sheet.mdx): A quick reference for contributors.
+- [Repo structure](./repo_structure.mdx): Learn about the structure of the LangChain repository.
+- [Documentation style guide](./documentation_style_guide.mdx): Learn how to write documentation for LangChain.
+- [FAQ](./faq.mdx): Frequently asked questions about contributing to LangChain.

docs/docs/contributing/reference/repo_structure.mdx

@@ -49,6 +49,6 @@ The `/libs` directory contains the code for the LangChain packages.
 
 To learn more about how to contribute code see the following guidelines:
 
-- [Code](./code.mdx) Learn how to develop in the LangChain codebase.
-- [Integrations](./integrations.mdx) to learn how to contribute to third-party integrations to langchain-community or to start a new partner package.
-- [Testing](./testing.mdx) guidelines to learn how to write tests for the packages.
+- [Code](../how_to/code.mdx) Learn how to develop in the LangChain codebase.
+- [Integrations](../how_to/integrations.mdx) to learn how to contribute to third-party integrations to langchain-community or to start a new partner package.
+- [Testing](../how_to/testing.mdx) guidelines to learn how to write tests for the packages.

docs/scripts/notebook_convert.py

@@ -3,7 +3,8 @@ import os
 import re
 import sys
 from pathlib import Path
-from typing import Iterable, Tuple
+from typing import Iterable, Tuple, List
+import tqdm
 
 import nbformat
 from nbconvert.exporters import MarkdownExporter
@@ -153,23 +154,31 @@ def _convert_notebook(
 
 
 if __name__ == "__main__":
-    intermediate_docs_dir = Path(sys.argv[1])
-    output_docs_dir = Path(sys.argv[2])
+    intermediate_docs_dir = Path(sys.argv[1]).absolute()
+    output_docs_dir = Path(sys.argv[2]).absolute()
 
     source_paths_arg = os.environ.get("SOURCE_PATHS")
-    source_paths: Iterable[Path]
+    source_paths: List[Path]
     if source_paths_arg:
         source_path_strs = re.split(r"\s+", source_paths_arg)
         source_paths_stripped = [p.strip() for p in source_path_strs]
-        source_paths = [intermediate_docs_dir / p for p in source_paths_stripped if p]
+        source_paths_all = [
+            intermediate_docs_dir / p for p in source_paths_stripped if p
+        ]
+        source_paths = [p for p in source_paths_all if p.name.endswith(".ipynb")]
     else:
-        source_paths = intermediate_docs_dir.glob("**/*.ipynb")
+        source_paths = list(intermediate_docs_dir.glob("**/*.ipynb"))
 
     with multiprocessing.Pool() as pool:
-        pool.map(
-            _process_path,
-            (
-                (notebook_path, intermediate_docs_dir, output_docs_dir)
-                for notebook_path in source_paths
-            ),
+        list(
+            tqdm.tqdm(
+                pool.imap(
+                    _process_path,
+                    (
+                        (notebook_path, intermediate_docs_dir, output_docs_dir)
+                        for notebook_path in source_paths
+                    ),
+                ),
+                total=len(source_paths),
+            )
         )

docs/sidebars.js

@@ -377,13 +377,32 @@ module.exports = {
     },
   ],
   contributing: [
+    {
+      type: "doc",
+      label: "Welcome contributors",
+      id: "contributing/index",
+    },
     {
       type: "category",
-      label: "Contributing",
+      label: "How to contribute",
+      link: {type: 'doc', id: 'contributing/how_to/index'},
+      collapsible: true,
       items: [
         {
           type: "autogenerated",
-          dirName: "contributing",
+          dirName: "contributing/how_to",
+        },
+      ],
+    },
+    {
+      type: "category",
+      label: "Reference",
+      link: {type: 'doc', id: 'contributing/reference/index'},
+      collapsible: true,
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "contributing/reference",
         },
       ],
     },

docs/vercel_requirements.txt

@@ -9,3 +9,4 @@ langchain-nvidia-ai-endpoints
 langchain-elasticsearch
 urllib3==1.26.18
 nbconvert==7.16.4
+tqdm==4.66.4