记录 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