貢獻文件#

貢獻文件對所有使用 pandas 的人都有好處。我們鼓勵您協助我們改善文件，而且您不需要是 pandas 專家才能這麼做！事實上，有些文件的部分在專家撰寫後反而更糟。如果您看不懂文件中的某個部分，在您弄懂後更新相關部分是確保它能幫助下一個人的好方法。請瀏覽問題頁面，以取得目前關於 Pandas 文件的所有公開問題清單。

關於 pandas 文件#

文件以reStructuredText撰寫，這幾乎就像用一般英文撰寫，並使用Sphinx建立。Sphinx 文件有一個優秀的reST 簡介。檢閱 Sphinx 文件，以對文件執行更複雜的變更。

關於文件的一些其他重要資訊

  • pandas 文件包含兩個部分：程式碼本身的文件字串和此資料夾中的文件doc/。

    文件字串提供個別函數使用方式的明確說明，而此資料夾中的文件包含每個主題的教學式概觀，以及一些其他資訊（最新消息、安裝等）。

  • 文件字串遵循 pandas 慣例，基於Numpy 文件字串標準。請遵循 pandas 文件字串指南，取得如何撰寫正確文件字串的詳細說明。

  • 教學範例大量使用 IPython 指示 sphinx 擴充功能。此指示讓您將程式碼放入文件，並在文件建置期間執行。例如

    .. ipython:: python

    x = 2
    x**3

    將會呈現為

    In [1]: x = 2

In [2]: x**3
Out[2]: 8

    文件中幾乎所有程式碼範例都會在文件建置期間執行（並儲存輸出）。此方法表示程式碼範例將永遠是最新狀態，但確實讓文件建置變得稍微複雜一些。

  • 我們在 doc/source/reference 中的 API 文件檔案，會存放文件字串自動產生的文件。對於類別，有些細微差別會控制哪些方法和屬性會自動產生頁面。

    我們有兩個類別的自動摘要範本。

    1. _templates/autosummary/class.rst。當您想要自動產生每個公開方法和類別屬性的頁面時，請使用此範本。numpydoc 會自動將 Attributes 和 Methods 區段新增到類別的已呈現文件。請參閱 DataFrame 以取得範例。

    2. _templates/autosummary/class_without_autosummary。當您想要挑選方法/屬性的子集以自動產生頁面時，請使用此範本。使用此範本時，您應該在類別文件字串中包含 Attributes 和 Methods 區段。請參閱 CategoricalIndex 以取得範例。

    每個方法都應該包含在 doc/source/reference 中文件檔案之一的 toctree 中，否則 Sphinx 會發出警告。

公用程式指令碼 scripts/validate_docstrings.py 可用於取得 API 文件的 csv 總結。並驗證特定類別、函式或方法的文件字串中的常見錯誤。此總結也會比較在 doc/source/reference 中檔案中文件化方法的清單（用於產生 API 參考 頁面）和實際的公開方法。這將識別在 doc/source/reference 中文件化但實際上並非類別方法的方法，以及在 doc/source/reference 中未文件化的現有方法。

更新 pandas 文件字串#

在改善單一函式或方法的文件字串時，不一定需要建立完整的說明文件（請參閱下一節）。不過，有一個腳本會檢查文件字串（例如 DataFrame.mean 方法）

python scripts/validate_docstrings.py pandas.DataFrame.mean

這個腳本會指出一些格式化錯誤（如果有的話），也會執行並測試文件字串中包含的範例。請查看 pandas 文件字串指南，以取得如何格式化文件字串的詳細指南。

文件字串中的範例（「doctest」）必須是有效的 Python 程式碼，它會以確定性的方式傳回呈現的輸出，而且使用者可以複製並執行。這可以使用上述的腳本來檢查，並在 Travis 上進行測試。失敗的 doctest 會阻擋合併 PR。請查看文件字串指南中的 範例 部分，以取得讓 doctest 通過的一些提示和技巧。

在執行包含文件字串更新的 PR 時，最好在 github 上的留言中張貼驗證腳本的輸出。

如何建立 pandas 說明文件#

需求#

首先，您需要一個開發環境才能建立 pandas（請參閱 建立開發環境 的文件）。

建立說明文件#

那麼，您如何建立文件？在主控台中導覽至您本地的 doc/ 目錄，然後執行

python make.py html

然後您可以在資料夾中找到 HTML 輸出 doc/build/html/。

您第一次建置文件時，會花費相當長的時間，因為它必須執行所有程式碼範例，並建置所有產生的文件字串頁面。在後續的呼叫中，sphinx 將只嘗試建置已修改的頁面。

如果您想要執行完整清理建置，請執行

python make.py clean
python make.py html

您可以告訴 make.py 只編譯文件的一個單一區段，大幅減少檢查變更的周轉時間。

# omit autosummary and API section
python make.py clean
python make.py --no-api

# compile the docs with only a single section, relative to the "source" folder.
# For example, compiling only this guide (doc/source/development/contributing.rst)
python make.py clean
python make.py --single development/contributing.rst

# compile the reference docs for a single function
python make.py clean
python make.py --single pandas.DataFrame.join

# compile whatsnew and API section (to resolve links in the whatsnew)
python make.py clean
python make.py --whatsnew

相較之下，完整的文件建置可能需要 15 分鐘，但單一區段可能只需要 15 秒。後續的建置，只處理您已變更的部分，將會更快。

建置會自動使用您機器上可用的核心數，以加快文件建置速度。您可以覆寫此設定

python make.py html --num-jobs 4

在網路瀏覽器中開啟以下檔案，以查看您剛建置的完整文件 doc/build/html/index.html。

您會滿意地看到您新的、改良的文件！

建置主分支文件#

當 pull request 合併到 pandas main 分支時，文件的主要部分也會由 Travis-CI 建置。然後這些文件會在此處 託管，另請參閱 持續整合 區段。

預覽變更#

提交 pull request 後，GitHub Actions 會自動建置文件。若要檢視已建置的網站

  1. 等待 CI / Web and docs 檢查完成。

  2. 按一下其旁的 Details。

  3. 從 Artifacts 下拉式選單中，按一下 docs 或 website，將網站下載為 ZIP 檔案。