入門#

準備您的首次貢獻#

  1. 我們的文件使用 reStructured Text、Markdown 和 Jupyter 筆記本。

  2. 我們廣泛使用 Sphinx 來構建文件。

  3. 我們使用 Transifex 幫助將文件翻譯成多種語言。

  4. 我們的文件託管在 Read the Docs 上。

開發您的貢獻#

Jupyter 的文件分佈在幾個專案中，列在Jupyter 文件主頁上。這些說明適用於所有 Jupyter 專案，儘管有些專案有進一步的貢獻指南。

克隆儲存庫#

  1. 根據您要貢獻文件的專案，在 GitHub 上 fork 相應的專案儲存庫。

  2. 將儲存庫克隆到您的系統。

編輯文件原始檔#

專案的原始檔通常位於專案的 docs/source 目錄中。reStructured Text 檔名以 .rst 結尾，Jupyter 筆記本檔案以 .ipynb 結尾。

  1. 當使用 reStructured Text 原始檔時，在您喜歡的文字編輯器中對 .rst 檔案進行所需的更改。

  2. 如果需要編輯筆記本檔案，您需要根據安裝文件安裝 Jupyter 筆記本。然後，執行 Jupyter 筆記本並編輯所需的檔案。在儲存 Jupyter .ipynb 檔案之前，請清除輸出單元格。儲存檔案並測試您的更改。

測試更改#

應安裝 Sphinx 以測試您的文件更改。為獲得最佳結果，我們建議您安裝穩定的開發版本 Sphinx (pip install git+https://github.com/sphinx-doc/sphinx@stable) 或當前釋出的 Sphinx 版本 (pip install sphinx)。

此外，您可能需要以下軟體包：sphinxcontrib-spelling、sphinx_rtd_theme、nbsphinx、pyenchant、recommonmark 0.4.0 和 jupyter_sphinx_theme，可以透過 pip install sphinxcontrib-spelling sphinx_rtd_theme nbsphinx pyenchant recommonmark==0.4.0 jupyter_sphinx_theme 安裝。

如果您在 Linux 上，您可能還需要透過執行 sudo apt-get install enchant 來安裝 Enchant C 庫。

一旦一切都安裝完畢，應從 docs 目錄使用終端/命令列執行以下命令

  • make html 會構建文件的本地 html 版本。輸出訊息將顯示錯誤或提供 html 文件的位置。例如，提供的位置可能是 build/html，要在瀏覽器中檢視這些文件，請輸入 open build/html/index.html。

  • make linkcheck 將檢查文件中的外部連結是否有效或是否不再有效（即導致 500 未找到錯誤）。

注意：我們建議使用 Python 3.4+ 來構建文件。如果您正在編輯文件，可以使用 Python 2.7.9+ 或 Github 編輯器。

建立拉取請求#

一旦您對更改感到滿意，請按照上述說明提交 GitHub 拉取請求。如果文件更改與開放的 GitHub issue 相關，請在拉取請求訊息中提及 issue 編號。

專案審閱者將檢視您的更改並提供反饋或將您的更改合併到文件中。

提問#

請隨時在 Jupyter 的 Google Group 或 GitHub 上的開放 issue 中提問。