记录 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 的机制)的大部分基础
-
注意
过去 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
。