一份给NumPy/SciPy的文档做贡献的指南

将Sphinx与numpy约定结合使用时，应使用numpydoc扩展名，以便正确处理文档字符串。例如，Sphinx Parameters将从您的docstring中提取该 部分并将其转换为字段列表。使用numpydoc也将避免普通Sphinx在遇到-------------像sphinx期望在文档字符串中找到的节标题（例如）之类的numpy docstring约定时产生的reStructuredText错误。

本文档中描述的某些功能需要最新版本的 numpydoc。例如，Yields部分以numpydoc0.6 加入 。

它可以从：

请注意，对于numpy中的文档，没有必要 在示例的开头进行。但是，某些子模块（例如，默认情况下不会导入），您必须明确包含它们：import numpy as npfft``

  1. import numpy.fft

之后你可以使用它：

  1. np.fft.fft2(...)

为方便起见， 下面包含格式标准 和示例

numpydoc docstring指南

本文档描述了与Sphinx的numpydoc扩展一起使用的文档字符串的语法和最佳实践。

::: tip 注意

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

本文档中描述的某些功能需要最新版本的 numpydoc。例如，Yields部分以numpydoc0.6 加入。

:::

概述

我们主要遵循这里描述的标准Python样式约定：

关于代码文档的其他PEP：

使用代码检查器：

导入约定

在整个NumPy源和文档中使用以下导入约定：

  1. import numpy as np
  2. import matplotlib as mpl
  3. import matplotlib.pyplot as plt

不要缩写scipy。没有激励用例在现实世界中缩写它，所以我们在文档中避免它以避免混淆。

文档串标准

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

  1. """This is the form of a docstring.
  3. It can be spread over several lines.
  5. """

NumPy，SciPy和scikits遵循文档字符串的通用约定，提供一致性，同时还允许我们的工具链生成格式良好的参考指南。本文档描述了当前社区对此类标准的共识。如果您有改进建议，请将它们发布在numpy-discussion列表中。

我们的docstring标准使用重新结构化文本（reST）语法，并使用Sphinx（一种了解我们正在使用的特定文档样式的预处理器）呈现。虽然可以使用丰富的标记集，但我们将自己限制在一个非常基本的子集中，以便提供在纯文本终端上易于阅读的文档字符串。

一个指导原则是文本的人类读者优先于扭曲文档字符串，因此我们的工具产生了良好的输出。我们编写了预处理器来帮助Sphinx完成任务，而不是牺牲文档字符串的可读性。

文档字符串行的长度应保持为75个字符，以便于阅读文本终端中的文档字符串。

章节

docstring由标题分隔的许多部分组成（弃用警告除外）。每个标题应以连字符加下划线，并且章节顺序应与下面的描述一致。

函数文档字符串的各个部分是：

  1. Short summary

    A one-line summary that does not use variable names or the function name, e.g.

    1.  def add(a, b):
    2.    """The sum of two numbers.
    4.    """

    The function signature is normally found by introspection and displayed by the help function. For some functions (notably those written in C) the signature is not available, so we have to specify it as the first line of the docstring:

    1.  """
    2.  add(a, b)
    4.  The sum of two numbers.
    6.  """

  2. Deprecation warning

    A section (use if applicable) to warn users that the object is deprecated. Section contents should include:

    • In what NumPy version the object was deprecated, and when it will be removed.
    • Reason for deprecation if this is useful information (e.g., object is superseded, duplicates functionality found elsewhere, etc.).

    • New recommended way of obtaining the same functionality.

      This section should use the deprecated Sphinx directive instead of an underlined section header.

      1. .. deprecated:: 1.6.0
      2.       `ndobj_old` will be removed in NumPy 2.0.0, it is replaced by
      3.       `ndobj_new` because the latter works also with array subclasses.

  3. Extended Summary

    A few sentences giving an extended description. This section should be used to clarify functionality, not to discuss implementation detail or background theory, which should rather be explored in the Notes section below. You may refer to the parameters and the function name, but parameter descriptions still belong in the Parameters section.

  4. Parameters

    Description of the function arguments, keywords and their respective types.

    1.  Parameters
    2.  ----------
    3.  x : type
    4.      Description of parameter `x`.
    5.  y
    6.      Description of parameter `y` (with type not specified)

    Enclose variables in single backticks. The colon must be preceded by a space, or omitted if the type is absent.

    For the parameter types, be as precise as possible. Below are a few examples of parameters and their types.

    1.  Parameters
    2.  ----------
    3.  filename : str
    4.  copy : bool
    5.  dtype : data-type
    6.  iterable : iterable object
    7.  shape : int or tuple of int
    8.  files : list of str

    If it is not necessary to specify a keyword argument, use optional:

    1.  x : int, optional

    Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the description:

    1.  Description of parameter `x` (the default is -1, which implies summation
    2.  over all axes).

    When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:

    1.  order : {'C', 'F', 'A'}
    2.      Description of `order`.

    When two or more input parameters have exactly the same type, shape and description, they can be combined:

    1.  x1, x2 : array_like
    2.      Input arrays, description of `x1`, `x2`.

  5. Returns

    Explanation of the returned values and their types. Similar to the Parameters section, except the name of each return value is optional. The type of each return value is always required:

    1.  Returns
    2.  -------
    3.  int
    4.      Description of anonymous integer return value.

    If both the name and type are specified, the Returns section takes the same form as the Parameters section:

    1.  Returns
    2.  -------
    3.  err_code : int
    4.      Non-zero value indicates error code, or zero on success.
    5.  err_msg : str or None
    6.      Human readable error message, or None on success.
    7.  Yields

    Explanation of the yielded values and their types. This is relevant to generators only. Similar to the Returns section in that the name of each value is optional, but the type of each value is always required:

    1.  Yields
    2.  ------
    3.  int
    4.      Description of the anonymous integer return value.

    If both the name and type are specified, the Yields section takes the same form as the Returns section:

    1.  Yields
    2.  ------
    3.  err_code : int
    4.      Non-zero value indicates error code, or zero on success.
    5.  err_msg : str or None
    6.      Human readable error message, or None on success.

    Support for the Yields section was added in numpydoc version 0.6.

  6. Receives

    Explanation of parameters passed to a generator’s .send() method, formatted as for Parameters, above. Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring includes Receives it must also include Yields.

  7. Other Parameters

    An optional section used to describe infrequently used parameters. It should only be used if a function has a large number of keyword parameters, to prevent cluttering the Parameters section.

  8. Raises

    An optional section detailing which errors get raised and under what conditions:

    1.  Raises
    2.  ------
    3.  LinAlgException
    4.      If the matrix is not numerically invertible.

    This section should be used judiciously, i.e., only for errors that are non-obvious or have a large chance of getting raised.

  9. Warns

    An optional section detailing which warnings get raised and under what conditions, formatted similarly to Raises.

  10. Warnings

    An optional section with cautions to the user in free text/reST.

  11. See Also

    An optional section used to refer to related code. This section can be very useful, but should be used judiciously. The goal is to direct users to other functions they may not be aware of, or have easy means of discovering (by looking at the module docstring, for example). Routines whose docstrings further explain parameters used by this function are good candidates.

    As an example, for numpy.mean we would have:

    1.  See Also
    2.  --------
    3.  average : Weighted average

    When referring to functions in the same sub-module, no prefix is needed, and the tree is searched upwards for a match.

    Prefix functions from other sub-modules appropriately. E.g., whilst documenting the random module, refer to a function in fft by

    1.  fft.fft2 : 2-D fast discrete Fourier transform

    When referring to an entirely different module:

    1.  scipy.random.norm : Random variates, PDFs, etc.

    Functions may be listed without descriptions, and this is preferable if the functionality is clear from the function name:

    1.  See Also
    2.  --------
    3.  func_a : Function a with its description.
    4.  func_b, func_c_, func_d
    5.  func_e

  12. Notes

    An optional section that provides additional information about the code, possibly including a discussion of the algorithm. This section may include mathematical equations, written in LaTeX format:

    1.  The FFT is a fast implementation of the discrete Fourier transform:
    3.  .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}

    Equations can also be typeset underneath the math directive:

    1.  The discrete-time Fourier time-convolution property states that
    3.  .. math::
    5.      x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
    6.      another equation here

    Math can furthermore be used inline, i.e.

    1.  The value of :math:`\omega` is larger than 5.

    Variable names are displayed in typewriter font, obtained by using \mathtt{var}:

    1.  We square the input parameter `alpha` to obtain
    2.  :math:`\mathtt{alpha}^2`.

    Note that LaTeX is not particularly easy to read, so use equations sparingly.

    Images are allowed, but should not be central to the explanation; users viewing the docstring as text must be able to comprehend its meaning without resorting to an image viewer. These additional illustrations are included using:

    1.  .. image:: filename

    where filename is a path relative to the reference guide source directory.

  13. References

    References cited in the notes section may be listed here, e.g. if you cited the article below using the text [1]_, include it as in the list as follows:

    1.  .. [1] O. McNoleg, "The integration of GIS, remote sensing,
    2.    expert systems and adaptive co-kriging for environmental habitat
    3.    modelling of the Highland Haggis using object-oriented, fuzzy-logic
    4.    and neural-network techniques," Computers & Geosciences, vol. 22,
    5.    pp. 585-588, 1996.

    which renders as [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.

    Referencing sources of a temporary nature, like web pages, is discouraged. References are meant to augment the docstring, but should not be required to understand it. References are numbered, starting from one, in the order in which they are cited.

    ::: danger Warning

    References will break tables

    Where references like [1] appear in a tables within a numpydoc docstring, the table markup will be broken by numpydoc processing. See numpydoc issue #130

    :::

  14. Examples

    An optional section for examples, using the doctest format. This section is meant to illustrate usage, not to provide a testing framework – for that, use the tests/ directory. While optional, this section is very strongly encouraged.

    When multiple examples are provided, they should be separated by blank lines. Comments explaining the examples should have blank lines both above and below them:

    1.  >>> np.add(1, 2)
    2.  3
    4.  Comment explaining the second example
    6.  >>> np.add([1, 2], [3, 4])
    7.  array([4, 6])

    The example code may be split across multiple lines, with each line after the first starting with ‘… ‘:

    1.  >>> np.add([[1, 2], [3, 4]],
    2.  ...        [[5, 6], [7, 8]])
    3.  array([[ 6,  8],
    4.        [10, 12]])

    For tests with a result that is random or platform-dependent, mark the output as such:

    1.  >>> import numpy.random
    2.  >>> np.random.rand(2)
    3.  array([ 0.35773152,  0.38568979])  #random

    You can run examples as doctests using:

    1.  >>> np.test(doctests=True)
    2.  >>> np.linalg.test(doctests=True)  # for a single module

    In IPython it is also possible to run individual examples simply by copy-pasting them in doctest mode:

    1.  In [1]: %doctest_mode
    2.  Exception reporting mode: Plain
    3.  Doctest mode is: ON
    4.  >>> %paste
    5.  import numpy.random
    6.  np.random.rand(2)
    7.  ## -- End pasted text --
    8.  array([ 0.8519522 ,  0.15492887])

    It is not necessary to use the doctest markup <BLANKLINE> to indicate empty lines in the output. Note that the option to run the examples through numpy.test is provided for checking if the examples work, not for making the examples part of the testing framework.

    The examples may assume that import numpy as np is executed before the example code in numpy. Additional examples may make use of matplotlib for plotting, but should import it explicitly, e.g., import matplotlib.pyplot as plt. All other imports, including the demonstrated function, must be explicit.

    When matplotlib is imported in the example, the Example code will be wrapped in matplotlib’s Sphinx plot directive <http://matplotlib.org/sampledoc/extensions.html>_. When matplotlib is not explicitly imported, plot:: can be used directly if matplotlib.sphinxext.plot_directive is loaded as a Sphinx extension in conf.py.

Documenting 类

类文档字符串

使用与上面相同的部分（除了 Returns 之外的所有部分都适用）。 此处还应记录 constructor(init)，docstring 的 Parameters 部分详细说明了构造函数参数。

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

  1. Attributes
  2. ----------
  3. x : float
  4.     The X coordinate.
  5. y : float
  6.     The Y coordinate.

属性和具有自己的文档字符串的属性可以按名称简单列出：

  1. Attributes
  2. ----------
  3. real
  4. imag
  5. x : float
  6.     The X coordinate
  7. y : float
  8.     The Y coordinate

通常，没有必要列出类方法。那些不属于公共API的名称以下划线开头。然而，在某些情况下，一个类可能有很多方法，其中只有少数是相关的（例如，ndarray的子​​类）。然后，有一个额外的方法部分变得有用：

  1. class Photo(ndarray):
  2.     """
  3.     Array with associated photographic information.
  5.     ...
  7.     Attributes
  8.     ----------
  9.     exposure : float
  10.         Exposure in seconds.
  12.     Methods
  13.     -------
  14.     colorspace(c='rgb')
  15.         Represent the photo in the given colorspace.
  16.     gamma(n=1.0)
  17.         Change the photo's gamma exposure.
  19.     """

如果有必要解释私有方法（谨慎使用！），可以在扩展摘要或Notes部分中引用它。不要在方法部分列出私有方法。

需要注意的是 自我 的 不 列为方法的第一个参数。

方法文档字符串

像任何其他功能一样记录这些。不要包含 self在参数列表中。如果方法具有等效函数（例如，许多ndarray方法就是这种情况），则函数docstring应该包含详细的文档，而docstring方法应该引用它。仅提供简要摘要，另请参阅方法docstring中的部分。该方法应根据需要使用“ 退货”或“ 收益”部分。

记录类实例

属于NumPy API的类的实例（例如 np.r_
np，c_ ， np.index_exp 等）可能需要一些小心。要为这些实例提供有用的文档字符串，我们执行以下操作：

  • 单实例：如果只公开一个类的实例，请记录该类。示例可以使用实例名称。
  • 多个实例：如果公开了多个实例，则会__doc__在运行时写入每个实例的文档字符串并将其分配给实例的 属性。该类按常规进行记录，并且可以在Notes和See Also 部分中提及公开的实例。

记录生成器

应记录发电机，就像记录功能一样。唯一的区别是，应该使用Yields部分而不是Returns部分。numpydoc版本0.6中添加了对Yields部分的 支持。

记录常量

使用与适用的功能概述相同的部分：

  1. 1. summary
  2. 2. extended summary (optional)
  3. 3. see also (optional)
  4. 4. references (optional)
  5. 5. examples (optional)

常量的文档字符串在文本终端中不可见（常量是不可变类型，因此文档字符串不能像为类实例一样分配给它们），但会出现在使用Sphinx构建的文档中。

记录模块

每个模块都应该有一个至少包含摘要行的文档字符串。其他部分是可选的，并且应该在适当时使用与记录函数相同的顺序：

  1. 1. summary
  2. 2. extended summary
  3. 3. routine listings
  4. 4. see also
  5. 5. notes
  6. 6. references
  7. 7. examples

鼓励使用常规列表，特别是对于大型模块，很难通过查看源文件或__all__dict 来很好地概述所有功能。

请注意，许可证和作者信息虽然通常包含在源文件中，但不属于文档字符串。

其他要记住的要点

  • 等式：如上面的注释部分所述，LaTeX格式应保持最小。通常可以将方程式显示为Python代码或伪代码，这在终端中更易读。对于内联显示器，请使用双反键（如）。要在上方和下方显示空行，请使用双冒号并缩进代码，例如：y = np.sin(x)
  1. end of previous sentence::
  3.     y = np.sin(x)
  • 注释和警告：如果文档字符串中的某些点值得特别强调，则可以在警告的上下文附近（部分内部）使用注释或警告的reST指令。句法：
  1. .. warning:: Warning text.
  3. .. note:: Note text.

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

  • array_like：对于带有不仅可以有 ndarray 类型的参数的函数，还有可以转换为ndarray的类型（即标量类型，序列类型），可以使用 array_like 类型记录这些参数。
  • 链接：如果您需要在docstring中包含超链接，请注意某些文档字符串部分未被解析为标准reST，并且在这些部分中，numpydoc可能会被超链接目标混淆，例如：
  1. .. _Example: http://www.example.com

如果Sphinx构建发出表单警告 ，那就是正在发生的事情。要避免此问题，请使用内联超链接表单：WARNING: Unknown target name: "example"

  1. `Example <http://www.example.com>`_

常见的reST概念

对于段落，缩进很重要并且表示输出中的缩进。新段落标有空行。

使用*italics*，**bold**并且monospace如果需要任何的解释（但不包括变量名和文档测试代码或者多行代码）。变量，模块，函数和类名应该写在单个back-ticks（numpy）之间。

在此示例文档中可以找到更广泛的reST标记示例 ; 该快速参考是编辑时非常有用。

线间距和压痕很重要，应该仔细遵循。

结论

该文档本身是用ReStructuredText编写的。这个例子这里显示的格式是可用的。