記錄 IPython#

注意

這完全複製自舊的 IPython wiki，目前正在開發中。本開發指南的許多資訊已過時。

在為 IPython 貢獻程式碼時，您應該力求清晰和一致，而不是陷入風格的束縛。基本上，‘記錄一切，力求一致，做有意義的事情。’

總的來說，我們遵循像 Python 本身或 NumPy 這樣主要專案中現有的 Python 實踐，本文件為 IPython 提供了一些額外的細節。

獨立文件#

所有獨立文件都應使用 reStructuredText [reStructuredText]_ 進行標記和格式化，並以純文字（.txt）檔案的形式編寫。所有此類文件都應放置在 IPython 原始碼樹的 docs/source 目錄中。或者，如果合適，應使用適當命名的子目錄。此位置的文件將作為 IPython 文件的主要來源。

實際的 HTML 和 PDF 文件是使用 Sphinx [Sphinx]_ 文件生成工具構建的。安裝 Sphinx 後，您可以透過以下方式自行構建 html 文件：

$ cd ipython-mybranch/docs
$ make html

我們對 Sphinx 的使用與 matplotlib [Matplotlib]_ 非常接近。我們正在使用 matplotlib 團隊編寫的一些 Sphinx 工具和擴充套件，並且將主要遵循他們的約定，這些約定在他們的文件指南 [MatplotlibDocGuide]_ 中得到了很好的闡述。因此，以下是 matplotlib 文件指南的刪節版本，經 matplotlib 團隊許可後改編。

如果您正在網路瀏覽器中閱讀此內容，可以點選“顯示源”連結檢視以下示例的原始 reStructuredText。

一點 Python 程式碼

for i in range(10):
    print i,
print "A big number:",2**34

一個互動式 Python 會話

>>> from IPython.utils.path import get_ipython_dir
>>> get_ipython_dir()
'/home/fperez/.config/ipython'

一個 IPython 會話

In [7]: import IPython

In [8]: print "This IPython is version:",IPython.__version__
This IPython is version: 0.9.1

In [9]: 2+4
Out[9]: 6

一點 shell 程式碼

cd /tmp
echo "My home directory is: $HOME"
ls

文件字串格式#

好的文件字串非常重要。不幸的是，Python 本身只為文件字串提供了一個相當鬆散的標準 [PEP257]_，並且對於完整文件字串的所有不同部分，沒有普遍接受的約定。然而，NumPy 專案已經建立了一個非常合理的標準，並且開發了一些工具來支援將此類文件字串順利包含在 Sphinx 生成的手冊中。IPython 將不再發明另一個偽標準，而是今後使用 NumPy 約定進行文件編寫；我們保留了一些 NumPy 支援工具的副本以保持自給自足，但我們會將我們對工具進行的任何改進或修復反饋給 NumPy 上游。

NumPy 文件指南 [NumPyDocGuide]_ 包含有關此標準的詳細資訊，對於快速概覽，NumPy 示例文件字串 [NumPyExampleDocstring]_ 是一份有用的讀物。

對於面向使用者的 API，我們力求嚴格遵循上述標準（即使這意味著更冗長和詳細的文件字串）。無論您在哪裡合理地期望人們透過

In [1]: some_function?

進行內省，文件字串都應遵循 NumPy 風格並相當詳細。

對於純粹的內部方法，只可能被其他擴充套件 IPython 本身的人閱讀，我們稍微放寬了一些要求，特別是對於意圖相當明顯的小/短方法和函式。我們仍然要求編寫文件字串，但它們可以更簡單。對於帶有單行文件字串的非常短的函式，您可以使用類似

def add(a, b):
   """The sum of two numbers.
   """
   code

對於較長的多行字串，則使用

def add(a, b):
   """The sum of two numbers.

   Here is the rest of the docs.
   """
   code

以下是另外兩個與程式碼文件相關的 PEP。儘管這兩個都被拒絕了，但其中的思想構成了 docutils（處理 reStructuredText 的機制）的大部分基礎

  • 文件字串處理系統框架

  • Docutils 設計規範

    注意

    過去 IPython 使用 epydoc，所以目前許多文件字串仍然使用 epydoc 約定。我們將隨著時間的推移更新它們，但所有新程式碼都應使用 NumPy 標準進行文件編寫。

構建和上傳#

構建好的文件儲存在一個單獨的倉庫中。透過一些 github 魔法，它們會自動作為網站公開。它的工作原理如下：

  • 您需要安裝 sphinx 和 latex。在 Ubuntu 中，安裝 texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended。從 PyPI 安裝最新版本的 sphinx (pip install sphinx)。

  • 確保 IPython 的開發版本在您的系統路徑中排在第一位。您可以使用虛擬環境，或者修改您的 PYTHONPATH。

  • 切換到 docs 目錄，並執行 make gh-pages。這將以 html 和 pdf 格式構建您更新的文件，然後自動檢出文件倉庫的最新版本，將構建好的文件複製到其中，並提交您的更改。

  • 在網路瀏覽器中開啟構建好的文件，並檢查它們是否符合預期。

  • （在為新的標記版本構建文件時，您必須將其連結新增到 index.rst，然後執行 python build_index.py 以更新 index.html。提交更改。）

  • 使用 git push 上傳文件。這僅在您擁有文件倉庫的寫入許可權時才有效。

  • 如果您正在構建的版本不是當前的開發分支，也不是標記版本，那麼您必須直接執行 gh-pages.py，使用 python gh-pages.py <version>，而不是使用 make gh-pages。