From e438fe6be9f609b4229fe4c7688899425f758072 Mon Sep 17 00:00:00 2001 From: Eugene Yurtsev Date: Wed, 14 Feb 2024 17:55:09 -0500 Subject: [PATCH] Docs: Contributing changes (#17551) A few minor changes for contribution: 1) Updating link to say "Contributing" rather than "Developer's guide" 2) Minor changes after going through the contributing documentation page. --- .github/CONTRIBUTING.md | 41 +----------------------- Makefile | 7 +++- docs/api_reference/create_api_rst.py | 33 +++++++++++++++---- docs/docs/contributing/documentation.mdx | 3 +- docs/docs/contributing/index.mdx | 11 +++++-- docs/docusaurus.config.js | 2 +- 6 files changed, 45 insertions(+), 52 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 484ebd1f38..d90322e897 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -3,43 +3,4 @@ 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. -To learn about how to contribute, please follow the [guides here](https://python.langchain.com/docs/contributing/) - -## 🗺️ Guidelines - -### 👩‍💻 Ways to contribute - -There are many ways to contribute to LangChain. Here are some common ways people contribute: - -- [**Documentation**](https://python.langchain.com/docs/contributing/documentation): Help improve our docs, including this one! -- [**Code**](https://python.langchain.com/docs/contributing/code): Help us write code, fix bugs, or improve our infrastructure. -- [**Integrations**](https://python.langchain.com/docs/contributing/integrations): Help us integrate with your favorite vendors and tools. - -### 🚩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. - -### 🙋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. - -### Contributor Documentation - -To learn about how to contribute, please follow the [guides here](https://python.langchain.com/docs/contributing/) +To learn how to contribute to LangChain, please follow the [contribution guide here](https://python.langchain.com/docs/contributing/). \ No newline at end of file diff --git a/Makefile b/Makefile index c21d230ab4..db50dfeed3 100644 --- a/Makefile +++ b/Makefile @@ -15,7 +15,12 @@ docs_build: docs/.local_build.sh docs_clean: - rm -r _dist + @if [ -d _dist ]; then \ + rm -r _dist; \ + echo "Directory _dist has been cleaned."; \ + else \ + echo "Nothing to clean."; \ + fi docs_linkcheck: poetry run linkchecker _dist/docs/ --ignore-url node_modules diff --git a/docs/api_reference/create_api_rst.py b/docs/api_reference/create_api_rst.py index 9413d90423..65fbb6a4e6 100644 --- a/docs/api_reference/create_api_rst.py +++ b/docs/api_reference/create_api_rst.py @@ -14,7 +14,6 @@ from pydantic import BaseModel ROOT_DIR = Path(__file__).parents[2].absolute() HERE = Path(__file__).parent - ClassKind = Literal["TypedDict", "Regular", "Pydantic", "enum"] @@ -323,30 +322,52 @@ def _package_dir(package_name: str = "langchain") -> Path: def _get_package_version(package_dir: Path) -> str: - with open(package_dir.parent / "pyproject.toml", "r") as f: - pyproject = toml.load(f) + """Return the version of the package.""" + try: + with open(package_dir.parent / "pyproject.toml", "r") as f: + pyproject = toml.load(f) + except FileNotFoundError as e: + print( + f"pyproject.toml not found in {package_dir.parent}.\n" + "You are either attempting to build a directory which is not a package or " + "the package is missing a pyproject.toml file which should be added." + "Aborting the build." + ) + exit(1) return pyproject["tool"]["poetry"]["version"] -def _out_file_path(package_name: str = "langchain") -> Path: +def _out_file_path(package_name: str) -> Path: """Return the path to the file containing the documentation.""" return HERE / f"{package_name.replace('-', '_')}_api_reference.rst" -def _doc_first_line(package_name: str = "langchain") -> str: +def _doc_first_line(package_name: str) -> str: """Return the path to the file containing the documentation.""" return f".. {package_name.replace('-', '_')}_api_reference:\n\n" def main() -> None: """Generate the api_reference.rst file for each package.""" + print("Starting to build API reference files.") for dir in os.listdir(ROOT_DIR / "libs"): + # Skip any hidden directories + # Some of these could be present by mistake in the code base + # e.g., .pytest_cache from running tests from the wrong location. + if not dir.startswith("."): + print("Skipping dir:", dir) + continue + if dir in ("cli", "partners"): continue else: + print("Building package:", dir) _build_rst_file(package_name=dir) - for dir in os.listdir(ROOT_DIR / "libs" / "partners"): + partner_packages = os.listdir(ROOT_DIR / "libs" / "partners") + print("Building partner packages:", partner_packages) + for dir in partner_packages: _build_rst_file(package_name=dir) + print("API reference files built.") if __name__ == "__main__": diff --git a/docs/docs/contributing/documentation.mdx b/docs/docs/contributing/documentation.mdx index d2f2ef4cef..a7468600b7 100644 --- a/docs/docs/contributing/documentation.mdx +++ b/docs/docs/contributing/documentation.mdx @@ -17,7 +17,7 @@ Similar to linting, we recognize documentation can be annoying. If you do not wa ### Install dependencies - [Quarto](https://quarto.org) - package that converts Jupyter notebooks (`.ipynb` files) into mdx files for serving in Docusaurus. -- `poetry install` from the monorepo root +- `poetry install --with lint,docs --no-root` from the monorepo root. ### Building @@ -49,7 +49,6 @@ make api_docs_linkcheck The docs are linted from the monorepo root. To lint the docs, run the following from there: ```bash -poetry install --with lint,typing make lint ``` diff --git a/docs/docs/contributing/index.mdx b/docs/docs/contributing/index.mdx index 366664ed03..d25212f286 100644 --- a/docs/docs/contributing/index.mdx +++ b/docs/docs/contributing/index.mdx @@ -15,8 +15,9 @@ There are many ways to contribute to LangChain. Here are some common ways people - [**Documentation**](./documentation.mdx): 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 +### 🚩 GitHub Issues Our [issues](https://github.com/langchain-ai/langchain/issues) page is kept up to date with bugs, improvements, and feature requests. @@ -31,7 +32,13 @@ 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. -### 🙋Getting Help +### 💭 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 diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 29ca5618c4..352a225c9d 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -188,7 +188,7 @@ const config = { }, { to: "/docs/contributing", - label: "Developer's guide", + label: "Contributing", }, { type: "docSidebar",