记录 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 团队许可使用。

如果你在网络浏览器中阅读此内容，你可以单击“显示源代码”链接以查看以下示例的原始 reStricturedText。

一段 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，然后自动检出文档存储库的最新版本，将构建的文档复制到其中，并提交您的更改。

  • 在 Web 浏览器中打开构建的文档，并检查它们是否符合预期。

  • （在为新标记版本构建文档时，您必须将其链接添加到 index.rst，然后运行 python build_index.py 以更新 index.html。提交更改。）

  • 使用 git push 上传文档。仅当您具有对文档存储库的写访问权限时，此操作才有效。

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

在此页面上
在 GitHub 上编辑
显示源代码