NumPy的文档 > NumPy / SciPy文档指南
将Sphinx与numpy约定结合使用时,应使用numpydoc
扩展名,以便正确处理文档字符串。例如,Sphinx Parameters
将从您的文档字符串中提取该
部分并将其转换为字段列表。使用numpydoc
还将避免纯Sphinx遇到numpy文档字符串约定(如-------------
sphinx期望在文档字符串中找不到的节头)(例如节标题)时产生的reStructuredText错误。
本文档中描述的某些功能要求使用最新版本的
numpydoc
。例如,在0.6 中添加了“ 收益”部分
numpydoc
。
可从以下位置获得:
请注意,对于numpy中的文档,没有必要
在示例开始时进行。但是,默认情况下不会导入某些子模块(例如),并且您必须明确包括它们:import numpy as np
fft
import numpy.fft
之后,您可以使用它:
np.fft.fft2(...)
为了方便起见, 以下包含格式化标准 的示例
内容
本文档介绍了与Sphinx的numpydoc扩展一起使用的文档字符串的语法和最佳实践。
vim-flake8插件,用于使用flake8自动检查语法和样式
NumPy源代码和文档中使用以下导入约定:
import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt
不要缩写scipy
。在现实世界中没有激励用例来简化它,因此我们在文档中避免使用它以免造成混淆。
文档字符串(docstring)是描述模块,函数,类或方法定义的字符串。文档字符串是对象(object.__doc__
)的特殊属性,为了保持一致,它用三重双引号引起来,即:
"""This is the form of a docstring.
It can be spread over several lines.
"""
NumPy,SciPy和scikits遵循文档字符串的通用约定,该约定提供了一致性,同时还允许我们的工具链生成格式正确的参考指南。本文描述了当前社区对此类标准的共识。如果您有改进的建议,请将其发布在numpy-discussion列表上。
我们的文档字符串标准使用重组文本(reST)语法,并使用Sphinx(可理解我们正在使用的特定文档样式的预处理器)进行呈现。尽管可以使用丰富的标记集,但我们将自己限制在一个非常基本的子集中,以便提供易于在纯文本终端上阅读的文档字符串。
一个指导原则是,文本的人类读者优先于扭曲的文档字符串,因此我们的工具可产生不错的输出。我们没有牺牲文档字符串的可读性,而是编写了预处理器来协助Sphinx完成其任务。
文档字符串行的长度应保持为75个字符,以方便阅读文本终端中的文档字符串。
该文档字符串由多个由标题分隔的部分组成(弃用警告除外)。每个标题都应在连字符下划线,并且各节的顺序应与以下描述一致。
函数的文档字符串的各节为:
简短的摘要
不使用变量名或函数名的单行摘要,例如
def add(a, b):
"""The sum of two numbers.
"""
该功能签名通常是通过自省找到的,并由帮助功能显示。对于某些功能(尤其是用C编写的功能),签名不可用,因此我们必须将其指定为文档字符串的第一行:
"""
add(a, b)
The sum of two numbers.
"""
弃用警告
用于警告用户该对象已弃用的部分(如果适用)。本节内容应包括:
在哪个NumPy版本中,不赞成使用该对象,以及何时将其删除。
如果这是有用的信息,则不赞成使用(例如,对象被取代,重复在其他地方找到的功能等)。
推荐的获得相同功能的新方法。
本节应使用deprecated
Sphinx指令而不是带下划线的节标题。
.. deprecated:: 1.6.0
`ndobj_old` will be removed in NumPy 2.0.0, it is replaced by
`ndobj_new` because the latter works also with array subclasses.
扩展摘要
一些句子提供了扩展的描述。本部分应用于阐明功能,而不是讨论实现细节或背景理论,而应在下面的“ 注释”部分中进行探讨。您可以参考参数和函数名称,但是参数描述仍属于“ 参数”部分。
参量
函数参数,关键字及其各自类型的描述。
Parameters
----------
x : type
Description of parameter `x`.
y
Description of parameter `y` (with type not specified)
将变量括在单个反引号中。冒号之前必须有一个空格,如果没有类型,则将其省略。
对于参数类型,请尽可能精确。以下是一些参数及其类型的示例。
Parameters
----------
filename : str
copy : bool
dtype : data-type
iterable : iterable object
shape : int or tuple of int
files : list of str
如果没有必要指定关键字参数,请使用
optional
:
x : int, optional
可选关键字参数具有默认值,这些默认值显示为功能签名的一部分。它们也可以在说明中进行详细说明:
Description of parameter `x` (the default is -1, which implies summation
over all axes).
当参数只能采用一组固定值中的一个时,这些值可以用大括号列出,默认值排在最前面:
order : {'C', 'F', 'A'}
Description of `order`.
当两个或多个输入参数的类型,形状和描述完全相同时,可以将它们组合在一起:
x1, x2 : array_like
Input arrays, description of `x1`, `x2`.
退货
返回值及其类型的说明。与“ 参数”部分相似 ,但每个返回值的名称是可选的。始终需要每个返回值的类型:
Returns
-------
int
Description of anonymous integer return value.
如果同时指定了名称和类型,则“ 返回”部分的形式与“ 参数”部分的形式相同:
Returns
-------
err_code : int
Non-zero value indicates error code, or zero on success.
err_msg : str or None
Human readable error message, or None on success.
产量
产生值及其类型的说明。这仅与发电机有关。与“ 返回”部分相似,每个值的名称是可选的,但始终需要每个值的类型:
Yields
------
int
Description of the anonymous integer return value.
如果同时指定了名称和类型,则Yields部分采用与Returns部分相同的形式:
Yields
------
err_code : int
Non-zero value indicates error code, or zero on success.
err_msg : str or None
Human readable error message, or None on success.
在numpydoc版本0.6中添加了对Yields部分的支持。
收到
传递给生成器.send()
方法的参数的说明,格式与上述“参数”相同。由于像“收益率和收益率”一样,始终将单个对象传递给方法,因此可以描述单个参数或作为元组传递的位置参数。如果文档字符串包含“接收”,则它还必须包含“收益”。
其他参数
可选部分,用于描述不常用的参数。仅在函数具有大量关键字参数的情况下才应使用该参数,以免使“ 参数”部分混乱。
加薪
可选部分,详细说明出现哪些错误以及在何种情况下引发以下错误:
Raises
------
LinAlgException
If the matrix is not numerically invertible.
本节应谨慎使用,即,仅适用于非显而易见的错误或很有可能引发的错误。
警告
可选部分,详细说明发出哪些警告以及在何种情况下发出的警告,格式类似于“引发”。
警告事项
可选部分,以自由文本/ reST告诫用户。
也可以看看
用于引用相关代码的可选部分。本节可能非常有用,但应谨慎使用。目的是将用户引导到他们可能不知道的其他功能,或者通过简单的发现方式(例如,通过查看模块文档字符串)来引导用户。docstring进一步说明此函数使用的参数的例程是不错的选择。
例如,numpy.mean
我们将有:
See Also
--------
average : Weighted average
当引用同一子模块中的功能时,不需要前缀,并且向上搜索树以查找匹配项。
前缀适当地来自其他子模块。例如,在记录random
模块时,
fft
通过
fft.fft2 : 2-D fast discrete Fourier transform
当引用完全不同的模块时:
scipy.random.norm : Random variates, PDFs, etc.
可能列出的功能没有描述,如果从功能名称中可以清楚地看到功能,则这是首选:
See Also
--------
func_a : Function a with its description.
func_b, func_c_, func_d
func_e
笔记
可选部分,提供有关代码的其他信息,可能包括对算法的讨论。本部分可能包括以LaTeX格式编写的数学方程式 :
The FFT is a fast implementation of the discrete Fourier transform:
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
也可以在math指令下排版方程式:
The discrete-time Fourier time-convolution property states that
.. math::
x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
another equation here
数学还可以内联使用,即
The value of :math:`\omega` is larger than 5.
变量名称以打字机字体显示,可通过使用\mathtt{var}
以下命令获得
:
We square the input parameter `alpha` to obtain
:math:`\mathtt{alpha}^2`.
请注意,LaTeX并不是特别容易阅读,因此请谨慎使用方程式。
图片是允许的,但不应成为解释的中心;以文本形式查看文档字符串的用户必须能够理解其含义,而无需借助图像查看器。这些其他插图包括使用:
.. image:: filename
其中filename是相对于参考指南源目录的路径。
参考文献
注释部分中引用的参考文献可能会在此处列出,例如,如果您使用文本引用了以下文章[1]_
,请在列表中包括以下内容:
.. [1] O. McNoleg, "The integration of GIS, remote sensing,
expert systems and adaptive co-kriging for environmental habitat
modelling of the Highland Haggis using object-oriented, fuzzy-logic
and neural-network techniques," Computers & Geosciences, vol. 22,
pp. 585-588, 1996.
呈现为1:
O. McNoleg,“使用面向对象,模糊逻辑和神经网络技术对高地哈吉斯群岛的环境栖息地建模进行的GIS,遥感,专家系统和自适应协同克里格的集成”,《计算机与地球科学》,第一卷。22,第585-588页,1996年。
不鼓励引用诸如网页之类的临时性资源。参考旨在增加文档字符串,但不要求理解它。参考文献从一开始按引用的顺序编号。
例子
示例的可选部分,使用doctest格式。本部分旨在说明用法,而不是提供测试框架–为此,请使用tests/
目录。虽然是可选的,但强烈建议此部分。
提供多个示例时,应将它们用空白行分隔。解释示例的注释的上方和下方均应有空白行:
>>> np.add(1, 2)
3
Comment explaining the second example
>>> np.add([1, 2], [3, 4])
array([4, 6])
示例代码可以分为多行,第一行之后的每一行均以“ ...”开头:
>>> np.add([[1, 2], [3, 4]],
... [[5, 6], [7, 8]])
array([[ 6, 8],
[10, 12]])
对于结果是随机的或与平台有关的测试,将输出标记为:
>>> import numpy.random
>>> np.random.rand(2)
array([ 0.35773152, 0.38568979]) #random
您可以使用以下示例作为doctests运行示例:
>>> np.test(doctests=True)
>>> np.linalg.test(doctests=True) # for a single module
在IPython中,也可以简单地通过在doctest模式下复制粘贴单个示例来运行它们:
In [1]: %doctest_mode
Exception reporting mode: Plain
Doctest mode is: ON
>>> %paste
import numpy.random
np.random.rand(2)
## -- End pasted text --
array([ 0.8519522 , 0.15492887])
不必使用doctest标记<BLANKLINE>
来指示输出中的空行。注意,numpy.test
提供了贯穿示例运行的选项,用于检查示例是否有效,而不是使示例成为测试框架的一部分。
这些示例可以假定在numpy中的示例代码之前执行。其他示例可能会使用
matplotlib进行绘图,但应显式导入它,例如
。所有其他导入(包括已演示的功能)必须是明确的。import numpy as np
import matplotlib.pyplot as plt
在示例中导入matplotlib时,示例代码将包装在matplotlib的Sphinx`plot指令< http://matplotlib.org/sampledoc/extensions.html >`_中。如果未显式导入matplotlib,则如果将Splotx:作为Sphinx扩展名加载,
则可以直接使用
plot ::。matplotlib.sphinxext.plot_directive
conf.py
使用上面概述的相同部分(所有其他部分Returns
均适用)。构造函数(__init__
)也应在此处记录,文档字符串的Parameters部分将详细说明构造函数的参数。
位于“ 参数”部分下方的“ 属性”部分可用于描述该类的非方法属性:
Attributes
----------
x : float
The X coordinate.
y : float
The Y coordinate.
可以简单地按名称列出作为属性的属性,并具有自己的文档字符串:
Attributes
----------
real
imag
x : float
The X coordinate
y : float
The Y coordinate
通常,没有必要列出类方法。那些不属于公共API的名称的名称以下划线开头。但是,在某些情况下,一个类可能有很多方法,其中只有少数几个是相关的(例如ndarray的子类)。然后,增加一个“ 方法”部分将变得很有用:
class Photo(ndarray):
"""
Array with associated photographic information.
...
Attributes
----------
exposure : float
Exposure in seconds.
Methods
-------
colorspace(c='rgb')
Represent the photo in the given colorspace.
gamma(n=1.0)
Change the photo's gamma exposure.
"""
如果有必要说明私有方法(请谨慎使用!),请在扩展摘要或“ 注释”部分中进行引用。不要在方法部分列出私有方法。
需要注意的是自我的不列为方法的第一个参数。
属于NumPy API的类的实例(例如np.r_ np,c_,np.index_exp等)可能需要格外小心。为了给这些实例一个有用的文档字符串,我们执行以下操作:
单个实例:如果仅公开一个类的单个实例,请记录该类。示例可以使用实例名称。
多个实例:如果公开了多个实例,则会__doc__
在运行时将每个实例的文档字符串写入并分配给实例的
属性。该类照常记录,可以在“ 注释”和“ 另请参阅”
部分中提及暴露的实例。
在适用的地方使用与功能概述相同的部分:
1. summary
2. extended summary (optional)
3. see also (optional)
4. references (optional)
5. examples (optional)
常量的文档字符串将在文本终端中不可见(常量是不可变类型的,因此不能像类实例那样为它们分配文档字符串),但将显示在使用Sphinx生成的文档中。
每个模块都应具有至少包含摘要行的文档字符串。其他部分是可选的,并在适当时以与记录功能相同的顺序使用:
1. summary
2. extended summary
3. routine listings
4. see also
5. notes
6. references
7. examples
鼓励使用例行程序清单,特别是对于大型模块,对于大型模块而言,通过查看源文件或__all__
字典很难很好地了解所提供的所有功能。
请注意,虽然许可证和作者信息通常包含在源文件中,但它们不属于文档字符串。
公式:如上文“ 注释”部分所述,LaTeX格式应保持最小。通常,可以将方程式显示为Python代码或伪代码,这在终端中更具可读性。对于嵌入式显示,请使用双反引号(例如)。为了显示上下两行的空白,请使用双冒号并缩进代码,例如:y = np.sin(x)
end of previous sentence::
y = np.sin(x)
注释和警告:如果文档字符串中有一些值得特别强调的地方,则注释或警告的reST指令可在警告上下文附近(在节内)使用。句法:
.. warning:: Warning text.
.. note:: Note text.
谨慎使用它们,因为它们在文本终端中看起来不太好,并且通常不需要。警告可能有用的一种情况是标记尚未修复的已知错误。
array_like:对于带有参数的函数,这些参数不仅可以具有ndarray类型,而且还可以转换为ndarray类型(即标量类型,序列类型),这些参数可以用array_like类型进行记录。
链接:如果您需要在文档字符串中包括超链接,请注意,某些文档字符串部分没有被解析为标准reST,在这些部分中,numpydoc可能会被诸如以下内容的超链接目标所混淆:
.. _Example: http://www.example.com
如果Sphinx版本发布形式的警告,
那就是发生了什么。为避免此问题,请使用内联超链接形式:WARNING: Unknown target name: "example"
`Example <http://www.example.com>`_