记录 IPython#

注意

这是从旧的 IPython wiki 直接复制过来的，目前正在开发中。开发指南的这一部分中的许多信息已经过时。

在为 IPython 贡献代码时，你应该力求清晰和一致，而不陷入风格的束缚。基本上，'记录所有内容，尽量保持一致，做合理的事情。'

总的来说，我们遵循像Python本身或NumPy这样的大型项目中的现有Python实践，本文档为IPython提供了一些额外的细节。

独立文档#

所有独立文档应使用纯文本（.txt）文件编写，并使用reStructuredText [reStructuredText]_ 进行标记和格式化。所有此类文档应放置在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?

docstring 应遵循 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，尽管这两个 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 上传文档。这仅在你对文档仓库有写权限时有效。

  • 如果你正在构建的版本既不是当前的开发分支，也不是一个标记的发布版本，那么你必须直接使用 python gh-pages.py <version> 运行 gh-pages.py，而不是使用 make gh-pages。

On this page
Edit on GitHub
显示源代码