python scipy模块文档_numpy/scipy文档指南

本文档描述了与numpydoc扩展一起使用的docstring的语法和最佳实践 Sphinx _.

注解

有关附带的示例，请参见 example.py .

本文档中描述的某些功能需要最新版本的 numpydoc . 例如， 产量 节已添加到 numpydoc 0.6。

在numpy源代码和文档中使用以下导入约定：

import numpy as np

import matplotlib as mpl

import matplotlib.pyplot as plt

不要缩写 scipy . 在现实世界中没有动机的用例来缩写它，因此我们在文档中避免使用它以避免混淆。

文档字符串(docstring)是描述模块、函数、类或方法定义的字符串。docstring是对象的一个特殊属性 (object.__doc__ )为了保持一致性，用三个双引号括起来，即：

"""This is the form of a docstring.

It can be spread over several lines.

"""

NumPy ， SciPy, 而且，SciKits遵循一个为docStrings提供一致性的通用约定，同时也允许我们的工具链生成格式良好的参考指南。本文件描述了目前社区对该标准的共识。如果您有改进建议，请将其发布到 numpy-discussion list .

我们的docstring标准使用 re-structured text (reST) 语法，并使用 Sphinx (了解我们使用的特定文档样式的预处理程序)。虽然有一组丰富的标记可用，但我们将自己限制在一个非常基本的子集中，以便提供易于在纯文本终端上读取的docstring。

一个指导原则是，文本的人类读者优先于扭曲的docstring，这样我们的工具就可以产生好的输出。我们没有牺牲docstring的可读性，而是编写了预处理器来帮助 Sphinx 在它的任务中。

docstring行的长度应保持为75个字符，以便于在文本终端中读取docstring。

docstring由多个由标题分隔的部分组成(不包括折旧警告)。每个标题都应该用连字符加下划线，并且节的顺序应该与下面的描述一致。

函数的docstring部分包括：

简短摘要

不使用变量名或函数名的单行摘要，例如

def add(a, b):

"""The sum of two numbers.

"""

函数签名通常通过内省找到并由帮助函数显示。对于某些函数(尤其是用C编写的函数)，签名不可用，因此我们必须将其指定为docstring的第一行：

"""

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

------

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。

其他参数

用于描述不常用参数的可选部分。它应该只在一个函数有大量关键字参数时使用，以防止混淆 参数 部分。

加薪

一个可选的部分，详细说明在什么条件下出现了哪些错误：

Raises

------

LinAlgException

If the matrix is not numerically invertible.

本节应谨慎使用，即仅适用于不明显或有很大可能被提出的错误。

警告

一个可选部分，详细说明哪些警告会被引发，以及在什么条件下，格式与引发类似。

警告

一个可选部分，在自由文本/休息中向用户提供警告。

也见

用于引用相关代码的可选部分。本节非常有用，但应谨慎使用。目标是引导用户使用他们可能不知道的其他功能，或者使用简单的发现方法(例如，通过查看模块docstring)。其docstrings进一步解释此函数使用的参数的例程是很好的候选者。

例如， 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`.

注意乳胶不太容易阅读，所以要谨慎使用方程式。

图像是允许的，但不应是解释的中心；用户将docstring视为文本时，必须能够理解其含义，而无需借助图像查看器。这些附加插图包括使用：

.. image:: 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，“利用面向对象的模糊逻辑和神经网络技术，将地理信息系统、遥感、专家系统和自适应协同克里金整合到高地哈吉斯的环境栖息地建模中”，计算机与地球科学，第22卷，第585-588页，1996年。

不鼓励引用临时性的源，如网页。引用是为了扩充docstring，但不需要理解它。参考文献从一开始按引用顺序编号。

警告

引用将断开表

参考文献如 [1] 出现在numpydoc docstring中的表中，表标记将由numpydoc处理中断。见 numpydoc issue #130

实例

示例的可选部分，使用 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标记 指示输出中的空行。请注意，运行示例的选项 numpy.test 用于检查示例是否有效，而不是将示例作为测试框架的一部分。

这些例子可以假定 import numpy as np 在中的示例代码之前执行 * NumPy * . 其他示例可利用 Mat普特利布 用于绘图，但应显式导入，例如， import matplotlib.pyplot as plt . 所有其他导入，包括演示的函数，都必须是显式的。

在示例中导入matplotlib时，示例代码将被包装在 matplotlib's Sphinx `plot directive `_ . 未显式导入matplotlib时， plot:: 可以直接使用，如果 matplotlib.sphinxext.plot_directive 作为sphinx扩展加载到 conf.py .

使用与上述相同的部分(除 Returns 适用)。构造函数 (__init__ )也应该记录在这里 参数 docstring的部分详细介绍了构造函数参数。

安 属性 部分，位于 参数 节，可用于描述类的非方法属性：

Attributes

----------

x : float

The X coordinate.

y : float

The Y coordinate.

属性和拥有自己的docstring的属性可以简单地按名称列出：

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.

"""

如果需要解释私有方法(小心使用！)，可以在 扩展摘要 或 笔记 部分。不要在中列出私有方法 方法 部分。

注意 self 是 not 列为方法的第一个参数。

像记录其他功能一样记录这些功能。不包括 self 在参数列表中。如果一个方法有一个等价的函数(例如，许多ndarray方法就是这样)，那么函数docstring应该包含详细的文档，方法docstring应该引用它。只写简短的总结和 也见 方法docstring中的节。该方法应使用 返回 或 产量 第节，视情况而定。

作为numpy API一部分的类实例(例如 np.r_ np,c_ ， np.index_exp 等)可能需要注意。为了给这些实例一个有用的docstring，我们执行以下操作：

单实例：如果只公开一个类的单实例，则记录该类。示例可以使用实例名称。

多实例：如果公开了多个实例，则会为每个实例编写并分配docstring。 __doc__ 运行时的属性。类像往常一样被记录，暴露的实例可以在 笔记 和 也见 部分。

应像记录功能一样记录发电机。唯一的区别是应该使用 产量 节而不是 返回 部分。支持 产量 节已添加到 numpydoc 版本0.6。

在适用的情况下，使用与功能概述相同的部分：

1. summary

2. extended summary (optional)

3. see also (optional)

4. references (optional)

5. examples (optional)

常量的docstring在文本终端中不可见(常量的类型是不可变的，因此不能像类实例那样将docstring分配给它们)，但将出现在用sphinx构建的文档中。

每个模块都应该有一个包含至少一个摘要行的docstring。其他部分是可选的，在适当的情况下，应按照与文档功能相同的顺序使用：

1. summary

2. extended summary

3. routine listings

4. see also

5. notes

6. references

7. examples

鼓励常规列表，尤其是对于大型模块，很难通过查看源文件或 __all__ 迪克

请注意，许可证和作者信息虽然经常包含在源文件中，但不属于docstring。

方程式：如 笔记 上面的部分，乳胶格式应该保持在最低限度。通常可以将公式显示为python代码或伪代码，这在终端中更易于阅读。对于内联显示，使用双回线(如 y = np.sin(x) )对于上面和下面有空行的显示，请使用双冒号并缩进代码，如：

end of previous sentence::

y = np.sin(x)

注释和警告：如果docstring中有值得特别强调的点，则注释或警告的其余指令可以在警告上下文附近使用(在节内)。语法：

.. warning:: Warning text.

.. note:: Note text.

谨慎地使用这些，因为它们在文本终端中看起来不太好，而且通常不需要。警告可能有用的一种情况是标记尚未修复的已知错误。

array_like：对于接受参数的函数，这些参数不仅可以有一个类型 ndarray ，但也可以转换为ndarray的类型(即标量类型、序列类型)，这些参数可以用类型记录。 array_like .

链接：如果您需要在docstring中包含超链接，请注意，有些docstring部分不会被解析为标准的rest，在这些部分中，numpydoc可能会被超链接目标混淆，例如：

.. _Example: http://www.example.com

如果狮身人面像建筑发出形式警告 WARNING: Unknown target name: "example" ，那就是发生的事情。要避免此问题，请使用内联超链接表单：

`Example`_

对于段落，缩进是重要的，并指示输出中的缩进。新段落用空行标记。

使用 *italics* ， **bold** 和 ``monospace 如果需要任何解释(但不适用于变量名和doctest代码或多行代码)。变量、模块、函数和类名应写在单个反勾号之间。 (```numpy ''。

行距和缩进量很大，应仔细遵循。

此文档本身是用RestructedText编写的。 An example 可以使用此处显示的格式。