跳到主要內容
Open on GitHub

設定

LangChain 文件由兩個部分組成

  1. 主要文件：託管於 python.langchain.com，這個全面的資源作為主要面向使用者的文件。它涵蓋了廣泛的主題，包括教學、用例、整合等等，為使用 LangChain 進行建置提供了廣泛的指導。此文件的內容位於 monorepo 的 /docs 目錄中。
  2. 程式碼內文件：這是程式碼庫本身的文件，也用於產生外部面向的 API 參考。API 參考的內容是透過掃描程式碼庫中的 docstring 自動產生的。因此，我們要求開發人員妥善記錄他們的程式碼。

API 參考 主要由 sphinx 從程式碼自動產生，並由 Read the Docs 託管。

我們感謝所有對文件的貢獻，無論是修正錯字、新增教學或範例，無論是在主要文件還是 API 參考中。

與程式碼檢查類似，我們認識到文件可能會令人厭煩。如果您不想做，請聯絡專案維護者，他們可以協助您。我們不希望這成為貢獻良好程式碼的阻礙。

📜 主要文件​

主要文件的內容位於 monorepo 的 /docs 目錄中。

文件是使用 ipython notebook (.ipynb 檔案) 和 markdown (.mdx 檔案) 的組合編寫的。notebook 會轉換為 markdown，然後使用 Docusaurus 2 建置。

歡迎隨時為主要文件做出貢獻！ 🥰

修改文件後

  1. 執行程式碼檢查和格式化命令 (請參閱下文) 以確保文件格式良好且沒有錯誤。
  2. 選擇性地在本機建置文件，以驗證變更看起來是否良好。
  3. 使用變更建立 pull request。
  4. 您可以透過點擊 pull request Conversation 頁面上的 View deployment 或 Visit Preview 按鈕，預覽並驗證變更是否符合您的期望。這將帶您到文件變更的預覽。

⚒️ 在本機檢查和建置文件​

撰寫文件後，您可能想要在本機檢查和建置文件，以確保其外觀良好且沒有錯誤。

如果您無法在本機建置，也沒關係，因為您可以在 pull request 頁面上看到文件的預覽。

建置​

建置文件的程式碼位於 monorepo 的 /docs 目錄中。

在以下命令中，字首 api_ 表示這些是 API 參考的操作。

在建置文件之前，最好先清除建置目錄

make docs_clean
make api_docs_clean

接下來，您可以按照以下概述建置文件

make docs_build
make api_docs_build
提示

make api_docs_build 命令需要很長時間。如果您要對 API 文件進行外觀上的變更，並想查看它們的外觀，請使用

make api_docs_quick_preview

這將只建置 API 參考的一小部分子集。

最後，執行連結檢查器以確保所有連結都有效

make docs_linkcheck
make api_docs_linkcheck

檢查和格式化​

主要文件是從 monorepo 根目錄 進行檢查的。若要檢查主要文件，請從那裡執行以下命令

make lint

如果您有與格式相關的錯誤，您可以使用以下命令自動修正它們

make format

⌨️ 程式碼內文件​

程式碼內文件主要由 sphinx 從程式碼自動產生，並由 Read the Docs 託管。

為了使 API 參考有用，程式碼庫必須妥善記錄。這表示所有函式、類別和方法都應該有一個 docstring，說明它們的作用、參數是什麼以及傳回值是什麼。這通常是一個好的做法，但對於 LangChain 來說尤其重要，因為 API 參考是開發人員了解如何使用程式碼庫的主要資源。

我們通常遵循 Google Python 風格指南 來撰寫 docstring。

這是一個妥善記錄的函式範例


def my_function(arg1: int, arg2: str) -> float:
    """This is a short description of the function. (It should be a single sentence.)

    This is a longer description of the function. It should explain what
    the function does, what the arguments are, and what the return value is.
    It should wrap at 88 characters.

    Examples:
        This is a section for examples of how to use the function.

        .. code-block:: python

            my_function(1, "hello")

    Args:
        arg1: This is a description of arg1. We do not need to specify the type since
            it is already specified in the function signature.
        arg2: This is a description of arg2.

    Returns:
        This is a description of the return value.
    """
    return 3.14

檢查和格式化​

程式碼內文件是從屬於要記錄的套件的目錄中進行檢查的。

例如，如果您正在處理 langchain-community 套件，您會將工作目錄變更為 langchain-community 目錄

cd [root]/libs/langchain-community

然後您可以執行以下命令來檢查和格式化程式碼內文件

make format
make lint

驗證文件變更​

將文件變更推送到儲存庫後，您可以透過點擊 pull request Conversation 頁面上的 View deployment 或 Visit Preview 按鈕，預覽並驗證變更是否符合您的期望。這將帶您到文件變更的預覽。此預覽由 Vercel 建立。

此頁面是否對您有幫助？