docs: reorganize contributing docs (#27649)

langchain-ai · Oct 25, 2024 · cdb4b19 · cdb4b19
1 parent fbfc6bd
commit cdb4b19
Show file tree

Hide file tree

Showing 28 changed files with 150 additions and 49 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -1,3 +1,3 @@
 # LangChain Documentation
 
-For more information on contributing to our documentation, see the [Documentation Contributing Guide](https://python.langchain.com/docs/contributing/documentation)
+For more information on contributing to our documentation, see the [Documentation Contributing Guide](https://python.langchain.com/docs/contributing/how_to/documentation)
diff --git a/docs/api_reference/guide_imports.json b/docs/api_reference/guide_imports.json
diff --git a/docs/docs/contributing/code/guidelines.mdx → ...s/contributing/how_to/code/guidelines.mdx b/docs/docs/contributing/code/guidelines.mdx → ...s/contributing/how_to/code/guidelines.mdx
@@ -6,7 +6,7 @@ Here are some things to keep in mind for all types of contributions:
 - Fill out the checked-in pull request template when opening pull requests. Note related issues and tag relevant maintainers.
 - Ensure your PR passes formatting, linting, and testing checks before requesting a review.
   - If you would like comments or feedback on your current progress, please open an issue or discussion and tag a maintainer.
-  - See the sections on [Testing](/docs/contributing/code/setup#testing) and [Formatting and Linting](/docs/contributing/code/setup#formatting-and-linting) for how to run these checks locally.
+  - See the sections on [Testing](setup.mdx#testing) and [Formatting and Linting](setup.mdx#formatting-and-linting) for how to run these checks locally.
 - Backwards compatibility is key. Your changes must not be breaking, except in case of critical bug and security fixes.
 - Look for duplicate PRs or issues that have already been opened before opening a new one.
 - Keep scope as isolated as possible. As a general rule, your changes should not affect more than one package at a time.
@@ -29,7 +29,7 @@ or new agents/chains from outside contributors without an existing GitHub discus
 
 - New features must come with docs, unit tests, and (if appropriate) integration tests.
 - New integrations must come with docs, unit tests, and (if appropriate) integration tests.
-  - See [this page](/docs/contributing/integrations) for more details on contributing new integrations.
+  - See [this page](../integrations.mdx) for more details on contributing new integrations.
 - New functionality should not inherit from or use deprecated methods or classes.
 - We will reject features that are likely to lead to security vulnerabilities or reports.
 - Do not add any hard dependencies. Integrations may add optional dependencies.
diff --git a/docs/docs/contributing/code/index.mdx → docs/docs/contributing/how_to/code/index.mdx b/docs/docs/contributing/code/index.mdx → docs/docs/contributing/how_to/code/index.mdx
@@ -2,5 +2,5 @@
 
 If you would like to add a new feature or update an existing one, please read the resources below before getting started:
 
-- [General guidelines](/docs/contributing/code/guidelines/)
-- [Setup](/docs/contributing/code/setup/)
+- [General guidelines](guidelines.mdx)
+- [Setup](setup.mdx)
diff --git a/docs/docs/contributing/code/setup.mdx → docs/docs/contributing/how_to/code/setup.mdx b/docs/docs/contributing/code/setup.mdx → docs/docs/contributing/how_to/code/setup.mdx
@@ -71,7 +71,7 @@ To run unit tests in Docker:
 make docker_tests
 ```
 
-There are also [integration tests and code-coverage](/docs/contributing/testing/) available.
+There are also [integration tests and code-coverage](../testing.mdx) available.
 
 ### Only develop langchain_core or langchain_community
 

diff --git a/...docs/contributing/documentation/index.mdx → ...ntributing/how_to/documentation/index.mdx b/...docs/contributing/documentation/index.mdx → ...ntributing/how_to/documentation/index.mdx
@@ -3,5 +3,5 @@
 Documentation is a vital part of LangChain. We welcome both new documentation for new features and 
 community improvements to our current documentation. Please read the resources below before getting started:
 
-- [Documentation style guide](/docs/contributing/documentation/style_guide/)
-- [Setup](/docs/contributing/documentation/setup/)
+- [Documentation style guide](style_guide.mdx)
+- [Setup](setup.mdx)
diff --git a/...docs/contributing/documentation/setup.mdx → ...ntributing/how_to/documentation/setup.mdx b/...docs/contributing/documentation/setup.mdx → ...ntributing/how_to/documentation/setup.mdx
diff --git a/...ontributing/documentation/style_guide.mdx → ...ting/how_to/documentation/style_guide.mdx b/...ontributing/documentation/style_guide.mdx → ...ting/how_to/documentation/style_guide.mdx
@@ -11,9 +11,9 @@ organization and structure.
 ## Philosophy
 
 LangChain's documentation follows the [Diataxis framework](https://diataxis.fr).
-Under this framework, all documentation falls under one of four categories: [Tutorials](/docs/contributing/documentation/style_guide/#tutorials),
-[How-to guides](/docs/contributing/documentation/style_guide/#how-to-guides),
-[References](/docs/contributing/documentation/style_guide/#references), and [Explanations](/docs/contributing/documentation/style_guide/#conceptual-guide).
+Under this framework, all documentation falls under one of four categories: [Tutorials](#tutorials),
+[How-to guides](#how-to-guides),
+[References](#references), and [Explanations](#conceptual-guide).
 
 ### Tutorials
 

diff --git a/docs/docs/contributing/how_to/index.mdx b/docs/docs/contributing/how_to/index.mdx
@@ -0,0 +1,5 @@
+# How-to Guides
+
+- [**Documentation**](documentation/index.mdx): Help improve our docs, including this one!
+- [**Code**](code/index.mdx): Help us write code, fix bugs, or improve our infrastructure.
+- [**Integrations**](integrations.mdx): Help us integrate with your favorite vendors and tools.
diff --git a/docs/docs/contributing/integrations.mdx → ...docs/contributing/how_to/integrations.mdx b/docs/docs/contributing/integrations.mdx → ...docs/contributing/how_to/integrations.mdx
@@ -4,7 +4,7 @@ sidebar_position: 5
 
 # Contribute Integrations
 
-To begin, make sure you have all the dependencies outlined in guide on [Contributing Code](/docs/contributing/code/).
+To begin, make sure you have all the dependencies outlined in guide on [Contributing Code](code/index.mdx).
 
 There are a few different places you can contribute integrations for LangChain:
 
@@ -138,7 +138,7 @@ By default, this will include stubs for a Chat Model, an LLM, and/or a Vector St
 
 Some basic tests are presented in the `tests/` directory. You should add more tests to cover your package's functionality.
 
-For information on running and implementing tests, see the [Testing guide](/docs/contributing/testing/).
+For information on running and implementing tests, see the [Testing guide](testing.mdx).
 
 ### Write documentation
 

diff --git a/docs/docs/contributing/testing.mdx → docs/docs/contributing/how_to/testing.mdx b/docs/docs/contributing/testing.mdx → docs/docs/contributing/how_to/testing.mdx
diff --git a/docs/docs/contributing/index.mdx b/docs/docs/contributing/index.mdx
@@ -8,13 +8,21 @@ As an open-source project in a fast developing field, we are extremely open to c
 
 ## Tutorials
 
-Coming soon! We are working on tutorials to help you make your first contribution to the project.
+More coming soon! We are working on tutorials to help you make your first contribution to the project.
+
+- [**Make your first docs PR**](tutorials/docs.mdx)
 
 ## How-to Guides
 
-- [**Documentation**](/docs/contributing/documentation/): Help improve our docs, including this one!
-- [**Code**](/docs/contributing/code/): Help us write code, fix bugs, or improve our infrastructure.
-- [**Integrations**](integrations.mdx): Help us integrate with your favorite vendors and tools.
+- [**Documentation**](how_to/documentation/index.mdx): Help improve our docs, including this one!
+- [**Code**](how_to/code/index.mdx): Help us write code, fix bugs, or improve our infrastructure.
+- [**Integrations**](how_to/integrations.mdx): Help us integrate with your favorite vendors and tools.
+
+## Reference
+
+- [**Repository Structure**](reference/repo_structure.mdx): Understand the high level structure of the repository.
+- [**Review Process**](reference/review_process.mdx): Learn about the review process for pull requests.
+- [**Frequently Asked Questions (FAQ)**](reference/faq.mdx): Get answers to common questions about contributing.
 
 ## Community
 

diff --git a/docs/docs/contributing/faq.mdx → docs/docs/contributing/reference/faq.mdx b/docs/docs/contributing/faq.mdx → docs/docs/contributing/reference/faq.mdx
@@ -27,11 +27,11 @@ fork in order to enable this setting.
 
 ### Why hasn't my PR been reviewed?
 
-Please reference our [Review Process](/docs/contributing/review_process/).
+Please reference our [Review Process](review_process.mdx).
 
 ### Why was my PR closed?
 
-Please reference our [Review Process](/docs/contributing/review_process/).
+Please reference our [Review Process](review_process.mdx).
 
 ### I think my PR was closed in a way that didn't follow the review process. What should I do?
 

diff --git a/docs/docs/contributing/reference/index.mdx b/docs/docs/contributing/reference/index.mdx
@@ -0,0 +1,5 @@
+# Reference
+
+- [**Repository Structure**](repo_structure.mdx): Understand the high level structure of the repository.
+- [**Review Process**](review_process.mdx): Learn about the review process for pull requests.
+- [**Frequently Asked Questions (FAQ)**](faq.mdx): Get answers to common questions about contributing.
diff --git a/docs/docs/contributing/repo_structure.mdx → ...contributing/reference/repo_structure.mdx b/docs/docs/contributing/repo_structure.mdx → ...contributing/reference/repo_structure.mdx
@@ -52,14 +52,14 @@ There are other files in the root directory level, but their presence should be
 The `/docs` directory contains the content for the documentation that is shown
 at https://python.langchain.com/ and the associated API Reference https://python.langchain.com/api_reference/langchain/index.html.
 
-See the [documentation](/docs/contributing/documentation/) guidelines to learn how to contribute to the documentation.
+See the [documentation](../how_to/documentation/index.mdx) guidelines to learn how to contribute to the documentation.
 
 ## Code
 
 The `/libs` directory contains the code for the LangChain packages.
 
 To learn more about how to contribute code see the following guidelines:
 
-- [Code](/docs/contributing/code/): Learn how to develop in the LangChain codebase.
-- [Integrations](./integrations.mdx): 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/index.mdx): Learn how to develop in the LangChain codebase.
+- [Integrations](../how_to/integrations.mdx): 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.
diff --git a/docs/docs/contributing/review_process.mdx → ...contributing/reference/review_process.mdx b/docs/docs/contributing/review_process.mdx → ...contributing/reference/review_process.mdx
diff --git a/docs/docs/contributing/tutorials/docs.mdx b/docs/docs/contributing/tutorials/docs.mdx
@@ -0,0 +1,51 @@
+# Make your first docs PR
+
+This tutorial will guide you through making a simple documentation edit, like correcting a typo.
+
+### **Prerequisites**
+- GitHub account.
+- Familiarity with GitHub pull requests (basic understanding).
+
+---
+
+## Editing a Documentation Page on GitHub**
+
+Sometimes you want to make a small change, like fixing a typo, and the easiest way to do this is to use GitHub's editor directly.
+
+### **Steps**
+
+1. **Navigate to the documentation page in the LangChain docs:**
+   - On the documentation page, find the green "Edit this page" link at the bottom of the page.
+   - Click the button to be directed to the GitHub editor.
+   - If the file you're editing is a Jupyter Notebook (.ipynb) instead of a Markdown (.md, .mdx)
+        file, we recommend following the steps in section 3.
+
+2. **Fork the repository:**
+   - If you haven't already, GitHub will prompt you to fork the repository to your account.
+   - Make sure to fork the repository into your **personal account and not an organization** ([why?](../reference/faq.mdx#how-do-i-allow-maintainers-to-edit-my-pr)).
+   - Click the "Fork this repository" button to create a copy of the repository under your account.
+   - After forking, you'll automatically be redirected to the correct editor.
+
+3. **Make your changes:**
+   - Correct the typo directly in the GitHub editor.
+
+4. **Commit your changes:**
+   - Click the "Commit changes..." button at the top-right corner of the page.
+   - Give your commit a title like "Fix typo in X section."
+   - Optionally, write an extended commit description.
+   - Click "Propose changes"
+
+5. **Submit a pull request (PR):**
+   - GitHub will redirect you to a page where you can create a pull request.
+   - First, review your proposed changes to ensure they are correct.
+   - Click **Create pull request**.
+   - Give your PR a title like `docs: Fix typo in X section`.
+   - Follow the checklist in the PR description template.
+
+## Getting a Review
+
+Once you've submitted the pull request, it will be reviewed by the maintainers. You may receive feedback or requests for changes. Keep an eye on the PR to address any comments.
+
+Docs PRs are typically reviewed within a few days, but it may take longer depending on the complexity of the change and the availability of maintainers.
+
+For more information on reviews, see the [Review Process](../reference/review_process.mdx).
diff --git a/docs/docs/contributing/tutorials/index.mdx b/docs/docs/contributing/tutorials/index.mdx
@@ -0,0 +1,5 @@
+# Tutorials
+
+More coming soon! We are working on tutorials to help you make your first contribution to the project.
+
+- [**Make your first docs PR**](docs.mdx)
diff --git a/docs/docs/integrations/chat/index.mdx b/docs/docs/integrations/chat/index.mdx
@@ -11,7 +11,7 @@ keywords: [compatibility]
 :::info
 
 If you'd like to write your own chat model, see [this how-to](/docs/how_to/custom_chat_model/).
-If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/integrations/).
+If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/how_to/integrations/).
 
 :::
 

diff --git a/docs/docs/integrations/llms/index.mdx b/docs/docs/integrations/llms/index.mdx
@@ -17,7 +17,7 @@ Unless you are specifically using more advanced prompting techniques, you are pr
 :::info
 
 If you'd like to write your own LLM, see [this how-to](/docs/how_to/custom_llm/).
-If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/integrations/).
+If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/how_to/integrations/).
 
 :::
 

diff --git a/docs/docs/introduction.mdx b/docs/docs/introduction.mdx
@@ -91,8 +91,8 @@ See what changed in v0.3, learn how to migrate legacy code, read up on our versi
 ### [Security](/docs/security)
 Read up on [security](/docs/security) best practices to make sure you're developing safely with LangChain.
 
-### [Integrations](/docs/integrations/providers/)
+### [Integrations](integrations/providers/index.mdx)
 LangChain is part of a rich ecosystem of tools that integrate with our framework and build on top of it. Check out our growing list of [integrations](/docs/integrations/providers/).
 
-### [Contributing](/docs/contributing)
+### [Contributing](contributing/index.mdx)
 Check out the developer's guide for guidelines on contributing and help getting your dev environment set up.
diff --git a/docs/scripts/document_loader_feat_table.py b/docs/scripts/document_loader_feat_table.py
@@ -18,7 +18,7 @@
 :::info
 
 If you'd like to write your own document loader, see [this how-to](/docs/how_to/document_loader_custom/).
-If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/integrations/).
+If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/how_to/integrations/).
 
 :::
 

diff --git a/docs/scripts/kv_store_feat_table.py b/docs/scripts/kv_store_feat_table.py
@@ -18,7 +18,7 @@
 
 :::info
 
-If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/integrations/).
+If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/how_to/integrations/).
 
 :::
 

diff --git a/docs/scripts/partner_pkg_table.py b/docs/scripts/partner_pkg_table.py
@@ -122,7 +122,7 @@ def doc() -> str:
 :::info
 
 If you'd like to write your own integration, see [Extending LangChain](/docs/how_to/#custom).
-If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/integrations/).
+If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/how_to/integrations/).
 
 :::
 

diff --git a/docs/scripts/tool_feat_table.py b/docs/scripts/tool_feat_table.py
@@ -189,7 +189,7 @@
 :::info
 
 If you'd like to write your own tool, see [this how-to](/docs/how_to/custom_tools/).
-If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/integrations/).
+If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/how_to/integrations/).
 
 :::
 

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -427,24 +427,43 @@ module.exports = {
     },
   ],
   contributing: [
+    {
+      type: "doc",
+      label: "Welcome Contributors",
+      id: "contributing/index",
+    },
     {
       type: "category",
-      label: "Contributing",
-      items: [
-        "contributing/index",
-        "contributing/repo_structure",
-        "contributing/code/index",
-        { type: "doc", id: "contributing/code/guidelines", className: "hidden" },
-        { type: "doc", id: "contributing/code/setup", className: "hidden" },
-        "contributing/integrations",
-        "contributing/documentation/index",
-        { type: "doc", id: "contributing/documentation/style_guide", className: "hidden" },
-        { type: "doc", id: "contributing/documentation/setup", className: "hidden" },
-        "contributing/testing",
-        "contributing/review_process",
-        "contributing/faq",
-      ],
+      link: {type: 'doc', id: 'contributing/tutorials/index'},
+      label: "Tutorials",
       collapsible: false,
+      items: [{
+        type: 'autogenerated',
+        dirName: 'contributing/tutorials',
+        className: 'hidden',
+      }],
+    },
+    {
+      type: "category",
+      link: {type: 'doc', id: 'contributing/how_to/index'},
+      label: "How-to guides",
+      collapsible: false,
+      items: [{
+        type: 'autogenerated',
+        dirName: 'contributing/how_to',
+        className: 'hidden',
+      }],
+    },
+    {
+      type: "category",
+      link: {type: 'doc', id: 'contributing/reference/index'},
+      label: "Reference & FAQ",
+      collapsible: false,
+      items: [{
+        type: 'autogenerated',
+        dirName: 'contributing/reference',
+        className: 'hidden',
+      }],
     },
   ],
 };
diff --git a/docs/src/theme/NotFound/Content/index.js b/docs/src/theme/NotFound/Content/index.js
@@ -67,7 +67,7 @@ const suggestedLinks = {
     ]
   },
   "/docs/contributing/documentation/technical_logistics/": {
-    "canonical": "/docs/contributing/documentation/",
+    "canonical": "/docs/contributing/how_to/documentation/",
     "alternative": [
       "/v0.1/docs/contributing/documentation/technical_logistics/"
     ]
@@ -2894,7 +2894,7 @@ const suggestedLinks = {
   "/docs/expression_language/how_to/binding/": {"canonical": "/docs/how_to/binding/", "alternative": ["/v0.1/docs/expression_language/primitives/binding/"]},
   "/docs/expression_language/how_to/configure/": {"canonical": "/docs/how_to/configure/", "alternative": ["/v0.1/docs/expression_language/primitives/configure/"]},
   "/docs/expression_language/cookbook/prompt_llm_parser/": {"canonical": "/docs/how_to/sequence/", "alternative": ["/v0.1/docs/expression_language/get_started/"]},
-  "/docs/contributing/documentation/": {"canonical": "/docs/contributing/documentation/", "alternative": ["/v0.1/docs/contributing/documentation/technical_logistics/"]},
+  "/docs/contributing/documentation/": {"canonical": "/docs/contributing/how_to/documentation/", "alternative": ["/v0.1/docs/contributing/documentation/technical_logistics/"]},
   "/docs/expression_language/cookbook/": {"canonical": "/docs/how_to/#langchain-expression-language-lcel", "alternative": ["/v0.1/docs/expression_language/"]},
   "/docs/integrations/text_embedding/solar/": {"canonical": "/docs/integrations/text_embedding/upstage/"},
   "/docs/integrations/chat/solar/": {"canonical": "/docs/integrations/chat/upstage/"},

diff --git a/docs/vercel.json b/docs/vercel.json
@@ -89,6 +89,14 @@
     {
       "source": "/docs/troubleshooting/errors/:path((?:GRAPH_RECURSION_LIMIT|INVALID_CONCURRENT_GRAPH_UPDATE|INVALID_GRAPH_NODE_RETURN_VALUE|MULTIPLE_SUBGRAPHS)/?)*",
       "destination": "https://langchain-ai.github.io/langgraph/troubleshooting/errors/:path*"
+    },
+    {
+      "source": "/docs/contributing/:path((?:code|documentation|integrations|testing)(?:/|/.*/?)?)",
+      "destination": "/docs/contributing/how_to/:path"
+    },
+    {
+      "source": "/docs/contributing/:path((?:faq|repo_structure|review_process)/?)",
+      "destination": "/docs/contributing/reference/:path"
     }
   ]
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,7 +11,7 @@ keywords: [compatibility] @@
     :::info
     If you'd like to write your own chat model, see [this how-to](/docs/how_to/custom_chat_model/).
-    If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/integrations/).
+    If you'd like to contribute an integration, see [Contributing integrations](/docs/contributing/how_to/integrations/).
     :::
@@ Expand Down @@