记录 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 的机制）的大部分基础

构建和上传#

构建好的文档存储在一个单独的仓库中。通过一些 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。