本指南将帮助您决定要贡献什么,以及如何将其提交给官方 NumPy 文档。
NumPy 社区已经确立了改进其文档的坚定目标。我们定期在 Zoom 上举行文档会议(日期在numpy-discussion 邮件列表上宣布),欢迎每个人参与。如果你有问题或需要有人指导你迈出第一步 - 我们很乐意帮助。 会议记录在hackmd.io上,存储在NumPy 存档存储库中。
NumPy 文档已经详细涵盖了细节。 API 参考文档直接从代码中的docstrings生成,当构建文档时。尽管我们对用户公开的每个函数和类都有大致完整的参考文档,但是一些函数缺乏使用示例。
我们缺少的是更广泛范围的文档 - 教程,如何做以及解释。报告缺陷是另一种贡献的方式。 我们都在讨论。
我们渴望听到并修复文档缺陷。 但要解决最大的问题,我们最终不得不推迟或忽略一些错误报告。 以下是要解决的最佳缺陷。
首要任务是技术错误 - 缺少参数的文档字符串,函数/参数/方法的错误描述等。 其他“结构性”缺陷,如损坏的链接也优先处理。 所有这些修复都易于确认并放置。 如果你知道如何做,你可以提交一个拉取请求(PR)来修复,否则请提交一个问题。
拼写错误和拼写错误处于较低的层次; 我们乐意听到它们,但可能无法迅速修复。 这些也可以作为拉取请求或问题来处理。
显而易见的措辞错误(比如漏掉了“不”)属于拼写错误类别,但其他重新措辞 - 甚至是语法 - 需要判断,这提高了经营难度。 通过首先将修复作为问题呈现,了解一下情况。
一些在 C 扩展模块中定义的函数/对象,如 numpy.ndarray.transpose, numpy.array 等,在_add_newdocs.py中有其单独定义的文档字符串。
你在使用我们文档时的挫败感是我们修复问题的最佳指南。
如果您撰写了一个缺失的文档,您就加入了开源的最前线,但仅仅告诉我们缺少了什么就是一项有意义的贡献。如果您想撰写文档,请向邮件列表征求意见和反馈。如果您想提醒我们有差距,请提出问题。参见此问题作为示例。
如果您正在寻找主题,我们的官方文档路线图是NumPy 增强提案(NEP),NEP 44 - 重组 NumPy 文档。它确定了我们文档需要帮助的领域,并列出了我们想要看到的几个补充内容,包括 Jupyter 笔记本。
有写作有用文件的公式,四个公式几乎覆盖了所有内容。有四个公式是因为文档有四个类别——教程
、操作指南
、说明
和参考资料
。认识到文档以这种方式划分是 Daniele Procida 及其Diátaxis Framework的洞察。当您开始撰写文档或提议文档时,请考虑它将属于这四种类型中的哪种。### NumPy 教程
除了 NumPy 源代码树中的文档之外,您还可以将内容以 Jupyter Notebook 格式提交到NumPy 教程页面。这套教程和教育材料旨在为 NumPy 项目提供高质量资源,既供自学使用,也供教学使用。这些资源是在单独的 GitHub 存储库numpy-tutorials中开发的,您可以在那里查看现有的笔记本,提出问题以建议新主题或提交自己的教程作为拉取请求。### 更多有关贡献的信息
如果英语不是您的母语,或者您只能提出初步草稿,不用担心。开源是一个社区的努力。尽力而为——我们将帮助解决问题。
图像和现实数据使文本更引人入胜和有力,但请确保您使用的内容具有适当的许可和可用性。同样,即使是艺术作品的初步构思也可以被他人打磨。
现在,NumPy 接受的唯一数据格式是其他 Python 科学库如 pandas、SciPy 或 Matplotlib 所使用的格式。我们正在开发一个包,可以接受更多格式;有关详情,请联系我们。
NumPy 文档保留在源代码树中。要将您的文档放入文档库,您必须下载该源代码树,构建它,并提交一个拉取请求。如果 GitHub 和拉取请求对您来说是新的,请查阅我们的贡献者指南。
我们使用的标记语言是 reStructuredText (rST),它比 Markdown 更为复杂。Sphinx 是许多 Python 项目用来构建和链接项目文档的工具,它会将 rST 转换为 HTML 和其他格式。想了解更多关于 rST 的信息,可以查看 Quick reStructuredText Guide 或 reStructuredText Primer。
如果你发现任何可以补充到 NumPy 文档的有用材料,请通过 提交 issue 告诉我们。
你不需要直接为 NumPy 做贡献也能有所贡献。如果你在自己的博客上写了一篇教程、创建了 YouTube 视频、或者在 Stack Overflow 等网站上回答了问题,那都算是你的贡献。
我们当前的规则:
numpy.indices
的先例。当将 Sphinx 与 NumPy 约定一起使用时,你应该使用 numpydoc
扩展,这样你的文档字符串就会被正确处理。例如,Sphinx 会从你的文档字符串中提取 Parameters
部分并将其转换为字段列表。使用 numpydoc
还能避免 Sphinx 在遇到 NumPy 文档字符串约定(如部分标题 -------------
)时产生的 reStructuredText 错误,因为这些约定 Sphinx 并不会在文档字符串中预料到。
NumPy 文档可以从以下网站获取:
请注意,对于 NumPy 内部的文档,在示例开头无需执行 import numpy as np
。
请使用 numpydoc
格式标准,如他们的 示例所示。 ### 记录 C/C++ 代码
NumPy 使用Doxygen来解析特殊格式的 C/C++注释块。这生成 XML 文件,然后由Breathe转换为 RST,Sphinx 使用它。
完成文档化过程需要三个步骤:
尽管目前仍未设置要遵循的注释样式,但由于与当前现有的非索引注释块的相似之处,Javadoc 比其他注释更受欢迎。
注意
请参阅“代码文档化”。
这就是 Javadoc 样式的效果:
/**
* This a simple brief.
*
* And the details goes here.
* Multi lines are welcome.
*
* @param num leave a comment for parameter num.
* @param str leave a comment for the second parameter.
* @return leave a comment for the returned value.
*/
int doxy_javadoc_example(int num, const char *str);
这就是它的呈现方式:
int doxy_javadoc_example(int num, const char *str)
这是一个简单的简短描述。
详细信息在这里。欢迎多行。
参数:
返回:
返回值添加注释。
对于行内注释,您可以使用三斜杠。例如:
/**
* Template to represent limbo numbers.
*
* Specializations for integer types that are part of nowhere.
* It doesn't support with any real types.
*
* @param Tp Type of the integer. Required to be an integer type.
* @param N Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
public:
/// Default constructor. Initialize nothing.
DoxyLimbo();
/// Set Default behavior for copy the limbo.
DoxyLimbo(const DoxyLimbo<Tp, N> &l);
/// Returns the raw data for the limbo.
const Tp *data();
protected:
Tp p_data[N]; ///< Example for inline comment.
};
这就是它的呈现方式:
template<typename Tp, std::size_t N> class DoxyLimbo
代表悬崖数字的模板。
无处不在的整数类型的特殊化。它不支持任何真实的类型。
参数 Tp:
整数类型。需要是整数类型。
参数 N:
元素数量。
公共函数
DoxyLimbo()
默认构造函数。不初始化任何内容。
DoxyLimbo(const <, > &l)
设置复制悬崖的默认行为。
const *data()
返回悬崖的原始数据。
受保护的属性
p_data[]
内联注释示例。
注意
更多标签/命令,请查看www.doxygen.nl/manual/commands.html
。
@brief
开始一个用作简短描述的段落。默认情况下,文档块的第一句自动被视为简短描述,因为在 doxygen 配置中启用了选项JAVADOC_AUTOBRIEF。
@details
就像@brief
开始一个简短描述,@details
开始详细描述。您还可以开始新段落(空行),然后不需要@details
命令。
@param
为函数参数开始一个参数描述,后跟参数的描述。检查参数的存在,并在缺少或不在函数声明或定义中存在该(或任何其他)参数的文档时给出警告。
@return
开始为函数返回值描述。多个相邻的@return
命令将合并为一个段落。当遇到空行或其他分段命令时,@return
描述结束。
@code/@endcode
开始/结束一个代码块。代码块与普通文本不同。它被解释为源代码。
@rst/@endrst
开始/结束一个 reST 标记块。
看以下示例:
/**
* A comment block contains reST markup.
* @rst
* .. note::
*
* Thanks to Breathe_, we were able to bring it to Doxygen_
*
* Some code example::
*
* int example(int x) {
* return x * 2;
* }
* @endrst
*/
void doxy_reST_example(void);
这就是它的呈现方式:
void doxy_reST_example(void)
注释块包含 reST 标记。
一些代码示例:
int example(int x) {
return x * 2;
}
注意
并非所有的头文件都会自动收集。你必须在 Doxygen 的子配置文件中添加所需的 C/C++ 头文件路径。
子配置文件的唯一名称为 .doxyfile
,通常可以在包含有文档化头文件的目录附近找到。如果靠近(2 深度)你想添加的头文件的路径中没有配置文件,则需要创建一个新的配置文件。
子配置文件可以接受任何 Doxygen 配置选项,但不要覆盖或重新初始化任何配置选项,而只使用连接运算符 “+=”。例如:
# to specify certain headers
INPUT += @CUR_DIR/header1.h \
@CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
NPY_HAVE_FEATURE2
注意
@CUR_DIR 是一个模板常量,返回子配置文件的当前目录路径。
Breathe 提供了广泛的自定义指令,允许将 Doxygen 生成的文档转换为 reST 文件。
注意
欲了解更多信息,请查看“指令与配置变量”
doxygenfunction
这个指令生成单个函数的适当输出。函数名在项目中必须是唯一的。
.. doxygenfunction:: <function name>
:outline:
:no-link:
查看 示例 以查看它的工作原理。
doxygenclass
这个指令生成单个类的适当输出。它接受标准项目、路径、大纲和无链接选项,还有成员、protected-members、private-members、undoc-members、membergroups 和 members-only 选项:
.. doxygenclass:: <class name>
:members: [...]
:protected-members:
:private-members:
:undoc-members:
:membergroups: ...
:members-only:
:outline:
:no-link:
查看 doxygenclass 文档 https://breathe.readthedocs.io/en/latest/class.html#class-example 获取更多详细信息并查看其工作原理。
doxygennamespace
这个指令生成命名空间内容的适当输出。它接受标准项目、路径、大纲和无链接选项,还有 content-only、members、protected-members、private-members 和 undoc-members 选项。要引用嵌套的命名空间,必须提供完整的命名空间路径,例如 foo::bar 表示 foo 命名空间内的 bar 命名空间。
.. doxygennamespace:: <namespace>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
查看 doxygennamespace 文档 获取更多详细信息并查看其工作原理。
doxygengroup
这个指令生成 Doxygen 组的适当输出。可以使用特定的 Doxygen 标记在源注释中声明 Doxygen 组,详见 doxygen 分组文档。
它接受标准项目、路径、大纲和无链接选项,还有 content-only、members、protected-members、private-members 和 undoc-members 选项。
.. doxygengroup:: <group name>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
:inner:
了解更多细节并查看演示,请参阅doxygengroup 文档。
NumPy 社区已经确立了改进文档的明确目标。我们在 Zoom 上定期举行文档会议(会议日期在numpy-discussion 邮件列表上公布),欢迎大家参加。如果你有疑问或需要有人指导你的初步步骤,随时联系我们,我们很乐意帮助。会议记录保存在hackmd.io上,并存储在NumPy Archive 仓库中。
NumPy 文档已经涵盖了详细内容。API 参考文档直接从代码中的文档字符串生成,当生成文档时(如何构建文档),它们会为用户展示每个函数和类的参考文档,但部分函数缺乏使用示例。
我们缺乏范围更广泛的文档 - 教程,操作说明和解释。报告缺陷是另一种贡献方式。我们都讨论。
我们渴望听到并修复文档缺陷。但是为了解决最大的问题,我们不得不推迟或忽视一些缺陷报告。以下是优先处理的最佳缺陷。
最重要的是技术错误 - 缺少参数的文档字符串,对函数/参数/方法的错误描述等。其他“结构性”缺陷(例如损坏的链接)也会被优先处理。所有这些修复都很容易确认并实施。如果您知道如何操作,请提交 pull 请求 (PR)进行修正;否则,请打开一个问题。
拼写错误和拼写错误居于更低的位置;我们欢迎了解这种错误,但可能无法及时修复。这些问题也可以作为 pull 请求或问题处理。
显而易见的用词错误(例如遗漏了“not”)属于拼写错误类别,但是其他的改写 - 甚至是语法上的改写 - 需要判断,这增加了难度。可以首先将修复作为问题发表,以试探反应。
一些函数/对象,如 numpy.ndarray.transpose、numpy.array 等,在 C 扩展模块中定义,其文档字符串在_add_newdocs.py中单独定义。
您对我们文档的使用中的困扰是改进的最好指南。
如果您编写一份缺失的文档,您就加入了开源界的前线,但光是让我们知道缺了些什么就已经是一项有意义的贡献。如果您想编写一份文档,请通过邮件列表与我们进一步讨论想法和获取反馈。如果您想告诉我们有什么遗漏,请创建一个问题。你可以参考这个问题作为示例。
如果你在寻找话题,我们正式的文件路线图是一个NumPy Enhancement Proposal (NEP),NEP 44 - 重组 NumPy 文档。它确定了我们的文档需要帮助和我们想要看到的若干补充内容的领域,包括 Jupyter notebooks。
有关编写有用文档的公式,有四个公式包含几乎所有内容。之所以有四个公式,是因为有四类文档 - 教程
、操作指南
、解释
和参考文献
。文档被分成这种方式的洞察力归功于 Daniele Procida 及其Diátaxis Framework。当您开始编写或提议一份文档时,请考虑一下它将属于这四种类型中的哪一种。 ### NumPy 教程
除了包含在 NumPy 源代码树中的文档之外,您还可以将内容以 Jupyter Notebook 格式提交到NumPy Tutorials 页面。这套教程和教育材料旨在为 NumPy 项目提供高质量的资源,供自学和教授课程使用。这些资源是在一个单独的 GitHub 仓库 numpy-tutorials 中开发的,您可以查看现有的笔记本,提出问题以建议新主题,或者以拉取请求的方式提交自己的教程。 ### 关于贡献的更多信息
如果英语不是您的母语,或者您只能草拟出一个简略版本,不要担心。开源是一个社区的努力。尽力而为 - 我们会帮助修复问题。
图像和真实数据使文本更具吸引力和强大,但请确保您使用的内容具有适当的许可和可用性。在这方面,即使是一个粗略的艺术构思也可以由其他人润色。
目前,NumPy 只接受由其他 Python 科学库(如 pandas、SciPy 或 Matplotlib)使用的数据格式。我们正在开发一个可以接受更多格式的包;有关详细信息,请与我们联系。
NumPy 文档保存在源代码树中。要将您的文档添加到文档库中,您必须下载树状结构,构建它,然后提交拉取请求。如果 GitHub 和拉取请求对您来说是新的,请查看我们的 Contributor Guide。
我们的标记语言是 reStructuredText(rST),比 Markdown 更复杂。Sphinx 是许多 Python 项目用于构建和链接项目文档的工具,可将 rST 转换为 HTML 和其他格式。有关 rST 的更多信息,请参阅Quick reStructuredText Guide 或 reStructuredText Primer 文档框架
有写有用文档的公式,其中有四个公式几乎涵盖了所有内容。有四个公式是因为文档有四个分类 - 教程
,操作指南
,解释
和参考文献
。文档的这种划分方式属于 Daniele Procida 及其Diátaxis Framework的见解。在开始编写文档或提出文档建议时,请考虑它将属于哪种类型。
除了 NumPy 源代码树中的文档之外,您还可以将内容以 Jupyter Notebook 格式提交到NumPy Tutorials页面。这组教程和教育材料旨在为 NumPy 项目提供高质量的资源,既可用于自学,也可用于授课。这些资源是在一个单独的 GitHub 存储库numpy-tutorials中开发的,您可以查看现有的笔记本,开启问题以建议新主题,或者提交您自己的教程作为拉取请求。
如果英语不是您的母语,或者只能提供初稿,不要担心。开源是一个社区的努力。尽力而为 - 我们会帮助解决问题的。
图片和现实数据使文本更具吸引力和影响力,但请确保您使用的内容具有适当的许可证并可供使用。同样,在设计艺术品时,即使有一个初步的想法,也可以由其他人进一步完善。
目前,NumPy 仅接受其他 Python 科学库(如 pandas、SciPy 或 Matplotlib)也使用的数据格式。我们正在开发一种可以接受更多格式的软件包;有关详细信息,请与我们联系。
NumPy 文档保存在源代码树中。要将您的文档添加到文档库中,您必须下载树状结构,构建它,然后提交拉取请求。如果 GitHub 和拉取请求对您来说是新的,请查看我们的 Contributor Guide。
我们的标记语言是比 Markdown 更精细的 reStructuredText(rST)。Sphinx,许多 Python 项目用于构建和链接项目文档的工具,将 rST 转换为 HTML 和其他格式。有关 rST 的更多信息,请参阅 快速 reStructuredText 指南 或 reStructuredText 入门
如果您找到外部资料对 NumPy 文档有用,请通过 提出问题 告诉我们。
要为 NumPy 做贡献,您不必在此处做贡献。如果您在博客上撰写教程、制作 YouTube 视频或在 Stack Overflow 和其他网站上回答问题,则表示您已经做出了贡献。
我们当前的规则:
numpy.indices
的先例。当使用 Sphinx 与 NumPy 约定结合时,应使用 numpydoc
扩展,以便正确处理您的文档字符串。例如,Sphinx 将从您的文档字符串中提取 Parameters
部分并将其转换为字段列表。使用 numpydoc
还可以避免在遇到 NumPy 文档字符串约定时产生的 reStructuredText 错误,例如部分标题(例如 -------------
),这是 Sphinx 不希望在文档字符串中找到的。
它可从以下位置获取:
请注意,对于 NumPy 内的文档,不需要在示例开头执行 import numpy as np
。
请使用 numpydoc
格式标准,如它们的 示例 中所示。### 记录 C/C++ 代码
NumPy 使用Doxygen来解析特殊格式的 C/C++ 注释块。这会生成 XML 文件,然后由Breathe转换为 RST,最后由 Sphinx 使用。
完成文档过程需要三个步骤:
尽管仍然没有设置要遵循的注释样式,但由于与当前现有的非索引注释块的相似之处,Javadoc 更可取。
注意
请参阅“文档化代码”。
这是 Javadoc 风格的样子:
/**
* This a simple brief.
*
* And the details goes here.
* Multi lines are welcome.
*
* @param num leave a comment for parameter num.
* @param str leave a comment for the second parameter.
* @return leave a comment for the returned value.
*/
int doxy_javadoc_example(int num, const char *str);
以及它的渲染方式:
int doxy_javadoc_example(int num, const char *str)
这是一个简单的简要。
详细信息在此处。多行欢迎。
参数:
返回:
为返回的值留下注释。
对于行注释,您可以使用三条正斜杠。例如:
/**
* Template to represent limbo numbers.
*
* Specializations for integer types that are part of nowhere.
* It doesn't support with any real types.
*
* @param Tp Type of the integer. Required to be an integer type.
* @param N Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
public:
/// Default constructor. Initialize nothing.
DoxyLimbo();
/// Set Default behavior for copy the limbo.
DoxyLimbo(const DoxyLimbo<Tp, N> &l);
/// Returns the raw data for the limbo.
const Tp *data();
protected:
Tp p_data[N]; ///< Example for inline comment.
};
以及它的渲染方式:
template<typename Tp, std::size_t N> class DoxyLimbo
表示盲目数字的模板。
整数类型的专业化,属于无处。它不支持任何实际类型。
Param Tp:
整数的类型。必须是整数类型。
Param N:
元素数量。
公共函数
DoxyLimbo()
默认构造函数。什么也不初始化。
DoxyLimbo(const <, > &l)
设置复制盲目的默认行为。
const *data()
返回盲目的原始数据。
受保护的属性
p_data[]
内联注释示例。
注意
如需更多标签/命令,请参阅www.doxygen.nl/manual/commands.html
@brief
开始用作简要描述的段落。默认情况下,文档块的第一句话会自动被视为简要描述,因为在 doxygen 配置中启用了选项JAVADOC_AUTOBRIEF。
@details
就像@brief
开始一个简要描述一样,@details
开始详细描述。您也可以开始一个新的段落(空行),然后不需要@details
命令。
@param
开始一个函数参数的参数描述,参数名为,后跟参数的描述。检查参数的存在,并在函数声明或定义中缺少此(或任何其他)参数的文档时给出警告。
@return
为函数设置返回值描述。多个相邻的@return
命令将合并为一个段落。当遇到空行或其他分段命令时,@return
描述结束。
@code/@endcode
开始/结束一个代码块。代码块与普通文本有所不同。它被解释为源代码。
@rst/@endrst
开始/结束一个 reST 标记块。
看下面的示例:
/**
* A comment block contains reST markup.
* @rst
* .. note::
*
* Thanks to Breathe_, we were able to bring it to Doxygen_
*
* Some code example::
*
* int example(int x) {
* return x * 2;
* }
* @endrst
*/
void doxy_reST_example(void);
以及它的渲染方式:
void doxy_reST_example(void)
注释块包含 reST 标记。
一些代码示例:
int example(int x) {
return x * 2;
}
注意
并非所有的头文件都会被自动收集。你必须在 Doxygen 的子配置文件中添加所需的 C/C++ 头文件路径。
子配置文件具有独特的名称.doxyfile
,通常可以在包含文档头文件的目录附近找到。如果要添加的头文件所在路径(2 层深度)没有配置文件,就需要创建一个新的配置文件。
子配置文件可以接受任何 Doxygen 配置选项,但不应覆盖或重新初始化任何配置选项,而是只使用连接运算符“+=”。例如:
# to specify certain headers
INPUT += @CUR_DIR/header1.h \
@CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
NPY_HAVE_FEATURE2
注意
@CUR_DIR 是一个模板常量,返回子配置文件的当前目录路径。
Breathe 提供了各种自定义指令,允许将 Doxygen 生成的文档转换为 reST 文件。
注意
欲获取更多信息,请查阅“指令和配置变量”
doxygenfunction
此指令生成单个函数的适当输出。项目中函数名必须唯一。
.. doxygenfunction:: <function name>
:outline:
:no-link:
查看 示例 以了解它的运作方式。
doxygenclass
此指令生成单个类的适当输出。它使用标准项目、路径、大纲和无链接选项,另外还有成员、受保护成员、私有成员、未记录成员、成员组和仅成员选项。
.. doxygenclass:: <class name>
:members: [...]
:protected-members:
:private-members:
:undoc-members:
:membergroups: ...
:members-only:
:outline:
:no-link:
了解 doxygenclass 文档 https://breathe.readthedocs.io/en/latest/class.html#class-example 以获取更多详细信息,并了解它的运作方式。
doxygennamespace
此指令生成命名空间内容的适当输出。它使用标准项目、路径、大纲和无链接选项,另外还有仅内容、成员、受保护成员、私有成员和未记录成员选项。要引用嵌套命名空间,必须提供完整的命名空间路径,例如 foo::bar 表示 foo 命名空间内的 bar 命名空间。
.. doxygennamespace:: <namespace>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
查看 doxygennamespace 文档 以获取更多详细信息,并了解它的运作方式。
doxygengroup
此指令生成适当输出以展示 Doxygen 组的内容。doxygen 组可以通过源注释中特定的 doxygen 标记进行声明,参见 doxygen 组织文档。
它使用标准项目、路径、大纲和无链接选项,另外还有仅内容、成员、受保护成员、私有成员和未记录成员选项。
.. doxygengroup:: <group name>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
:inner:
查看doxygengroup 文档以获取更多详细信息并查看其实际操作。 ### 用户文档
我们当前的规则:
numpy.indices
的先例。当将Sphinx与 NumPy 约定结合使用时,应使用numpydoc
扩展,以使您的文档字符串被正确处理。例如,Sphinx 将从您的文档字符串中提取Parameters
部分并将其转换为字段列表。使用numpydoc
还将避免纯 Sphinx 在遇到像部分标题(如-------------
)这样的 NumPy 文档字符串约定时产生的 reStructuredText 错误,这是 Sphinx 不希望在文档字符串中找到的。
可从以下网址获取:
请注意,在 NumPy 文档中,不需要在示例开头执行import numpy as np
。
请按照他们的numpydoc
格式标准,如其示例所示。
NumPy 使用Doxygen来解析特殊格式的 C/C++注释块。这会生成 XML 文件,然后由Breathe转换为 RST,Sphinx 将使用它。
完成文档过程需要三个步骤:
尽管尚未设定注释风格以遵循,但由于与当前现有的非索引评论块相似,Javadoc 比其他风格更可取。
注意
请参阅“代码文档化”。
这就是 Javadoc 风格的样子:
/**
* This a simple brief.
*
* And the details goes here.
* Multi lines are welcome.
*
* @param num leave a comment for parameter num.
* @param str leave a comment for the second parameter.
* @return leave a comment for the returned value.
*/
int doxy_javadoc_example(int num, const char *str);
以下是呈现方式:
int doxy_javadoc_example(int num, const char *str)
这是一个简单的简介。
详细信息在这里。 欢迎多行输入。
参数:
返回:
为返回的值添加注释。
对于行注释,你可以使用三个正斜杠。例如:
/**
* Template to represent limbo numbers.
*
* Specializations for integer types that are part of nowhere.
* It doesn't support with any real types.
*
* @param Tp Type of the integer. Required to be an integer type.
* @param N Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
public:
/// Default constructor. Initialize nothing.
DoxyLimbo();
/// Set Default behavior for copy the limbo.
DoxyLimbo(const DoxyLimbo<Tp, N> &l);
/// Returns the raw data for the limbo.
const Tp *data();
protected:
Tp p_data[N]; ///< Example for inline comment.
};
以下是它的呈现方式:
template<typename Tp, std::size_t N> class DoxyLimbo
用于表示深渊数字的模板。
不支持任何真实类型的整数类型的特化。
参数 Tp:
整数的类型。 必须是一个整数类型。
参数 N:
元素的数量。
公共函数
DoxyLimbo()
默认构造函数。不初始化任何内容。
DoxyLimbo(const <, > &l)
设置复制深渊的默认行为。
const *data()
返回深渊的原始数据。
受保护的属性
p_data[]
行内注释的示例。
注意
更多标签/命令,请参阅www.doxygen.nl/manual/commands.html
@brief
开始一个作为简要描述的段落。默认情况下,文档块的第一句话会被自动视为简要描述,因为 Doxygen 配置中启用了选项JAVADOC_AUTOBRIEF。
@details
就像 @brief
开始简短的描述一样,@details
开始详细的描述。你也可以开始一个新的段落(空行),然后 @details
命令就不再需要了。
@param
开始一个函数参数的参数描述,参数名为,后面跟着参数的描述。会检查参数的存在性,如果函数声明或定义中缺少此(或任何其他)参数的文档,则会发出警告。
@return
开始一个函数的返回值描述。 多个相邻的 @return
命令会合并成一个段落。当遇到空行或其他部分命令时,@return
描述结束。
@code/@endcode
开始/结束一个代码块。代码块会与普通文本区别对待。它被解释为源代码。
@rst/@endrst
开始/结束一个 reST 标记块。
请看以下示例:
/**
* A comment block contains reST markup.
* @rst
* .. note::
*
* Thanks to Breathe_, we were able to bring it to Doxygen_
*
* Some code example::
*
* int example(int x) {
* return x * 2;
* }
* @endrst
*/
void doxy_reST_example(void);
以下是它的呈现方式:
void doxy_reST_example(void)
一个注释块包含 reST 标记。
一些代码示例:
int example(int x) {
return x * 2;
}
注意
并非所有头文件都会被自动收集。您必须在 Doxygen 的子配置文件中添加所需的 C/C++头路径。
子配置文件的唯一名称是.doxyfile
,您通常可以在包含文档头文件的目录附近找到它。如果您想添加的头文件所在的路径中没有配置文件,您需要创建一个新的配置文件。
子配置文件可以接受Doxygen的任何配置选项,但不会覆盖或重新初始化任何配置选项,只使用连接操作符“+=”。例如:
# to specify certain headers
INPUT += @CUR_DIR/header1.h \
@CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
NPY_HAVE_FEATURE2
注意
@CUR_DIR 是一个模板常量,返回子配置文件的当前目录路径。
Breathe 提供了丰富的自定义指令,允许将Doxygen生成的文档转换为 reST 文件。
注意
更多信息,请查阅 “Directives & Config Variables”
doxygenfunction
此指令会为单个函数生成相应输出。函数名称在项目中必须是唯一的。
.. doxygenfunction:: <function name>
:outline:
:no-link:
请查阅 示例 以实际操作。
doxygenclass
此指令会为单个类生成相应输出。它接受标准项目、路径、大纲和无链接选项,以及 members、protected-members、private-members、undoc-members、membergroups 和 members-only 选项:
.. doxygenclass:: <class name>
:members: [...]
:protected-members:
:private-members:
:undoc-members:
:membergroups: ...
:members-only:
:outline:
:no-link:
请查阅 doxygenclass 文档 https://breathe.readthedocs.io/en/latest/class.html#class-example 以获取更多详细信息并实际操作。
doxygennamespace
此指令会为命名空间的内容生成相应输出。它接受标准项目、路径、大纲和无链接选项,以及 content-only、members、protected-members、private-members 和 undoc-members 选项。要引用嵌套命名空间,必须提供完整的命名空间路径,例如 foo::bar 表示 foo 命名空间内的 bar 命名空间。
.. doxygennamespace:: <namespace>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
请查阅 doxygennamespace 文档 以获取更多详细信息并实际操作。
doxygengroup
此指令会为 doxygen 组的内容生成相应输出。可以在源注释中使用特定的 doxygen 标记来声明 doxygen 组,详见 doxygen 分组文档。
它接受标准项目、路径、大纲和无链接选项,以及 content-only、members、protected-members、private-members 和 undoc-members 选项。
.. doxygengroup:: <group name>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
:inner:
请查阅 doxygengroup 文档 以获取更多详细信息并实际操作。
虽然还没有设定要遵循的注释样式,但 Javadoc 与当前现有的非索引化注释块相似,因此更可取。
注意
Javadoc 样式如下:
/**
* This a simple brief.
*
* And the details goes here.
* Multi lines are welcome.
*
* @param num leave a comment for parameter num.
* @param str leave a comment for the second parameter.
* @return leave a comment for the returned value.
*/
int doxy_javadoc_example(int num, const char *str);
以下是渲染效果:
int doxy_javadoc_example(int num, const char *str)
这是一个简单简介。
具体内容如下。支持多行。
参数:
返回:
在返回值上留下注释。
对于行注释,您可以使用三个正斜杠。例如:
/**
* Template to represent limbo numbers.
*
* Specializations for integer types that are part of nowhere.
* It doesn't support with any real types.
*
* @param Tp Type of the integer. Required to be an integer type.
* @param N Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
public:
/// Default constructor. Initialize nothing.
DoxyLimbo();
/// Set Default behavior for copy the limbo.
DoxyLimbo(const DoxyLimbo<Tp, N> &l);
/// Returns the raw data for the limbo.
const Tp *data();
protected:
Tp p_data[N]; ///< Example for inline comment.
};
下面是如何呈现的:
template<typename Tp, std::size_t N> class DoxyLimbo
表示 limbo 数字的模板。
针对不存在任何实际类型的整数类型的特化。它不支持任何真实类型。
参数 Tp:
整数的类型。必须是整数类型。
参数 N:
元素的数量。
公共函数
DoxyLimbo()
默认构造函数。不初始化任何内容。
DoxyLimbo(const <, > &l)
设置将 limbo 复制的默认行为。
const *data()
返回 limbo 的原始数据。
保护属性
p_data[]
行内注释示例。
注意
更多标签/命令,请参考www.doxygen.nl/manual/commands.html
。
@brief
开始作为简要描述的段落。默认情况下,文档块的第一句被自动视为简要描述,因为在 Doxygen 配置中启用了JAVADOC_AUTOBRIEF选项。
@details
就像@brief
开始一个简要描述一样,@details
开始详细描述。您也可以开始一个新段落(空行),然后不需要@details
命令。
@param
开始函数参数的参数描述,后跟参数的描述。检查参数的存在性,如果缺少参数的文档或未在函数声明或定义中出现,则会发出警告。
@return
开始函数的返回值描述。多个相邻的@return
命令将被合并成一个段落。当遇到空行或其他分段命令时,@return
描述结束。
@code/@endcode
开始/结束代码块。代码块被视为源代码而非普通文本。
@rst/@endrst
开始/结束 reST 标记块。
看以下示例:
/**
* A comment block contains reST markup.
* @rst
* .. note::
*
* Thanks to Breathe_, we were able to bring it to Doxygen_
*
* Some code example::
*
* int example(int x) {
* return x * 2;
* }
* @endrst
*/
void doxy_reST_example(void);
下面是如何呈现的:
void doxy_reST_example(void)
一个注释块包含 reST 标记。
一些代码示例:
int example(int x) {
return x * 2;
}
注意
注意
更多标签/命令,请参考www.doxygen.nl/manual/commands.html
。
@brief
开始作为简要描述的段落。默认情况下,文档块的第一句被自动视为简要描述,因为在 Doxygen 配置中启用了JAVADOC_AUTOBRIEF选项。
@details
就像@brief
开始一个简要描述一样,@details
开始详细描述。您也可以开始一个新段落(空行),然后不需要@details
命令。
@param
开始函数参数描述,参数名为,后跟参数描述。会检查参数的存在,并且如果缺少此参数(或其他任何参数)的文档或在函数声明或定义中不存在,则会发出警告。
@return
开始函数返回值描述。多个相邻的 @return
命令将连接成一个段落。当遇到空行或其他分段命令时,@return
描述结束。
@code/@endcode
开始/结束一段代码。代码块与普通文本不同。它被解释为源代码。
@rst/@endrst
开始/结束一段 reST 标记。
请看下面的示例:
/**
* A comment block contains reST markup.
* @rst
* .. note::
*
* Thanks to Breathe_, we were able to bring it to Doxygen_
*
* Some code example::
*
* int example(int x) {
* return x * 2;
* }
* @endrst
*/
void doxy_reST_example(void);
以下是渲染的效果:
void doxy_reST_example(void)
注释块包含 reST 标记。
一些代码示例:
int example(int x) {
return x * 2;
}
注意
并非所有标头文件都会自动收集。您必须在 Doxygen 的子配置文件中添加所需的 C/C++ 标头路径。
子配置文件具有唯一名称.doxyfile
,您通常可以在包含文档化标头的目录附近找到它们。如果在您想要添加的标头所在的路径附近(2 层深度)找不到一个,则需要创建一个新的配置文件。
子配置文件可以接受任何Doxygen的配置选项,但不会覆盖或重新初始化任何配置选项,而只是使用连接运算符“+=”。例如:
# to specify certain headers
INPUT += @CUR_DIR/header1.h \
@CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
NPY_HAVE_FEATURE2
注意
@CUR_DIR 是一个模板常量,返回子配置文件的当前目录路径。
Breathe提供了各种自定义指令,允许将Doxygen生成的文档转换为 reST 文件。
注意
更多信息,请查看“指令与配置变量”
doxygenfunction
此指令为单个函数生成适当的输出。项目中必须确保函数名唯一。
.. doxygenfunction:: <function name>
:outline:
:no-link:
查看示例以查看其运作方式。
doxygenclass
此指令生成单个类的适当输出。它接受标准项目、路径、大纲和无链接选项,另外还有成员、受保护成员、私有成员、未文档化成员、成员组和仅成员选项:
.. doxygenclass:: <class name>
:members: [...]
:protected-members:
:private-members:
:undoc-members:
:membergroups: ...
:members-only:
:outline:
:no-link:
查看 doxygenclass 文档 https://breathe.readthedocs.io/en/latest/class.html#class-example 以获取更多详情并查看其运作方式。
doxygennamespace
此指令用于生成命名空间的内容适当输出。它采用标准的项目、路径、大纲和无链接选项,并额外提供内容、成员、受保护的成员、私有成员和未记录的成员选项。要引用嵌套命名空间,必须提供完整的命名空间路径,例如 foo::bar 表示 foo 命名空间中的 bar 命名空间。
.. doxygennamespace:: <namespace>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
查看doxygennamespace 文档以获取更多详细信息并查看其实际应用。
doxygengroup
此指令用于生成 doxygen 组的内容适当输出。可以通过源代码注释中的特定 doxygen 标记声明 doxygen 组,详见 doxygen 的分组文档。
它采用标准的项目、路径、大纲和无链接选项,还额外提供内容、成员、受保护的成员、私有成员和未记录的成员选项。
.. doxygengroup:: <group name>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
:inner:
查看doxygengroup 文档以获取更多详细信息并查看其实际应用。
doxygenfunction
此指令用于生成单个函数的适当输出。函数名在项目中必须是唯一的。
.. doxygenfunction:: <function name>
:outline:
:no-link:
查看示例以查看实际应用。
doxygenclass
此指令用于生成单个类的适当输出。它采用标准的项目、路径、大纲和无链接选项,并额外提供成员、受保护的成员、私有成员、未记录的成员、成员组和仅成员选项:
.. doxygenclass:: <class name>
:members: [...]
:protected-members:
:private-members:
:undoc-members:
:membergroups: ...
:members-only:
:outline:
:no-link:
查看*doxygenclass 文档https://breathe.readthedocs.io/en/latest/class.html#class-example_*以获取更多详细信息并查看其实际应用。
doxygennamespace
此指令用于生成命名空间的内容适当输出。它采用标准的项目、路径、大纲和无链接选项,并额外提供内容、成员、受保护的成员、私有成员和未记录的成员选项。要引用嵌套命名空间,必须提供完整的命名空间路径,例如 foo::bar 表示 foo 命名空间中的 bar 命名空间。
.. doxygennamespace:: <namespace>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
查看doxygennamespace 文档以获取更多详细信息并查看其实际应用。
doxygengroup
此指令用于生成 doxygen 组的内容适当输出。可以通过源代码注释中的特定 doxygen 标记声明 doxygen 组,详见 doxygen 的分组文档。
它采用标准的项目、路径、大纲和无链接选项,还额外提供内容、成员、受保护的成员、私有成员和未记录的成员选项。
.. doxygengroup:: <group name>
:content-only:
:outline:
:members:
:protected-members:
:private-members:
:undoc-members:
:no-link:
:inner:
查看doxygengroup 文档以获取更多详细信息并了解其运作方式。
numpy.array_api
支持 Array API v2022.12
f2py
的 meson
后端
f2py
的 bind(c)
支持
f2py
支持 iso_c_binding
np.pad
使用 mode=wrap
填充将保持与原始数据的严格倍数
long_t
和 ulong_t
axes
参数错误时,改变了错误消息和类型以获取 ufunc
where
使用,则定义 __array_ufunc__
的数组类可以覆盖 ufuncs
np.einsum
现在可以接受 object
dtype 的数组
NPY_ENABLE_CPU_FEATURES
环境变量
np.exceptions
命名空间
np.linalg
函数返回 NamedTuples
np.char
中的字符串函数与 NEP 42 自定义 dtype 兼容
NDArrayOperatorsMixin
指定其没有 __slots__
DTypePromotionError
np.ma.diff
在调用时不保留掩码的问题(使用参数 prepend/append)
numpy.logspace
现在支持非标量 base
参数
np.ma.dot()
现在支持非 2d 数组
np.dtypes
中公开 DType 类
numpy.lib.recfunctions.structured_to_unstructured
在更多情况下返回视图
np.argsort
更快
np.sort
更快
__array_function__
机制现在更快
ufunc.at
的速度可能更快
NpzFile
上的成员测试更快
msort
np.str0
和类似的现在已被弃用
array.fill(scalar)
可能行为略有不同
BufferError
symbol
character
字符串的 F2PY 支持
np.show_runtime
testing.assert_array_equal
的 strict
选项
np.unique
现在新增了equal_nan
参数
numpy.stack
,使用casting
和dtype
关键字参数
numpy.vstack
,使用casting
和dtype
关键字参数
numpy.hstack
,使用casting
和dtype
关键字参数
np.void
现在有一个dtype
参数
arange()
现在明确失败,带有dtype=str
numpy.typing
协议现在可以在运行时进行检查
np.isin
和np.in1d
的版本,适用于整数数组
masked_invalid
现在原地修改掩码
nditer
/NpyIter
允许分配所有操作数
genfromtxt
新增参数 ndmin
np.loadtxt
现在支持引号字符和单一转换函数
average
的 keepdims
参数
np.unique
新增参数 equal_nan
np.linalg.norm
保留浮点输入类型,即使结果是标量
NPY_RELAXED_STRIDES_CHECKING
已被移除
np.loadtxt
已经有了几处变化
ndarray.__array_finalize__
现在可调用
np.fromiter
现在接受对象和子数组
np.kron
现在保留子类信息
np.loadtxt
np.where
np.kron
loads
、ndfromtxt
和 mafromtxt
的已过期废弃
kth
值传递给 (arg-)partition
np.MachAr
类
numpy.vectorize
函数现在产生与基础函数相同的输出类
PCG64DSXM
和 PCG64
中修正了 advance
c_intp
精度
numpy.argmin
, numpy.argmax
现已添加keepdims
可选参数
bit_count
用于计算整数中 1 位的数量
ndim
和 axis
属性已添加到 numpy.AxisError
windows/arm64
目标的初步支持
.clang-format
文件
is_integer
现在可用于 numpy.floating
和 numpy.integer
ndarray
, dtype
和 number
现在可以在运行时进行下标化
ctypeslib.load_library
现在可以接受任何类似路径的对象
finfo
中添加了 smallest_normal
和 smallest_subnormal
属性
numpy.linalg.qr
接受堆叠矩阵作为输入
numpy.fromregex
现在接受os.PathLike
的实现
quantile
和percentile
添加新方法
nan<x>
函数添加了缺少的参数
PCG64DXSM
BitGenerator
.dtype
属性必须返回dtype
numpy.convolve
和numpy.correlate
的不精确匹配已被弃用
np.typeDict
已正式弃用
ndarray.ctypes
方法已被弃用
PolyBase
和未使用的PolyError
和PolyDomainError
__array_ufunc__
参数验证
__array_ufunc__
和附加的位置参数
Generator.uniform
中验证输入值
/usr/include
路径
dtype=...
比较的更改
dtype
和signature
参数的更改
signature=...
和 dtype=
的泛化和 casting
ufunc->type_resolver
和“type tuple”numpy.number
精度添加了一个 mypy 插件
numpy.number
子类
min_digits
参数
ndarray
添加了一个可以在运行时使用的别名
numpy.unwrap
的任意period
选项
np.unique
现在返回单个 NaN
Generator.rayleigh
和 Generator.geometric
的性能
np.save
和np.load
的性能,适用于小数组
numpy.piecewise
输出类现在与输入类匹配
permuted
函数
sliding_window_view
为 numpy 数组提供了滑动窗口视图
numpy.broadcast_shapes
是一个新的面向用户的函数
np.int
等内置类型的别名已被弃用
shape=None
已被弃用
mode
和searchside
的不精确匹配已被弃用
outer
和ufunc.outer
用于矩阵的已弃用
ndindex
的ndincr
方法已被弃用
__len__
和__getitem__
的 ArrayLike 对象
isinstance(dtype, np.dtype)
而不是 type(dtype) is not np.dtype
axis=None
的情况下,连接中的相同类型强制转换
numpy.broadcast_arrays
的结果进行写操作将导出只读缓冲区
operator.concat
函数现在对数组参数引发 TypeError
nickname
属性
float->timedelta
和 uint64->timedelta
的提升将引发 TypeError
numpy.genfromtxt
正确地解包结构化数组
mgrid
、r_
等在非默认精度输入下一致返回正确的输出
IndexError
__array_interface__["data"]
元组的第一个元素必须是整数
poly1d
尊重所有零参数的 dtype
np.array
中发现虚类型
PyArray_DescrCheck
宏
np.ndarray
和np.void_
的大小已更改
numpy.all
和numpy.any
函数的where
关键字参数
numpy
函数mean
、std
、var
的where
关键字参数
numpy.fft
函数的norm=backward
、forward
关键字选项
numpy.typing
在运行时可访问
__f2py_numpy_version__
属性。
mypy
测试
cov
和corrcoef
的dtype
选项
__str__
)
repr
numpy.core.records.fromfile
现在支持类文件对象
divmod(1., 0.)
及相关函数行为变更
np.linspace
在整数上现在使用向下取整
numpy.insert
和numpy.delete
现在不能在 0 维数组上传递轴
numpy.delete
不再忽略越界索引
numpy.insert
和numpy.delete
不再接受非整数索引
numpy.delete
不再将布尔索引转换为整数
numpy.random.Generator.dirichlet
改变随机变量流
PyArray_ConvertToCommonType
中的标量提升
np.ediff1d
在 to_end
和 to_begin
参数下的类型转换行为
multiarray.int_asbuffer
numpy.distutils.compat
已被移除
issubdtype
不再将 float
解释为 np.floating
round
输出结果与 Python 保持一致
numpy.ndarray
构造函数不再将 strides=()
解释为 strides=None
SeedSequence
不再与生成冲突
dtype=object
numpy.rec
的工厂函数中传递 shape=0
已被弃用
np.complexfloating
标量的 round
方法已被弃用
numpy.ndarray.tostring()
已被弃用,建议使用 tobytes()
const
维度的更好支持
numpy.frompyfunc
现在接受一个 identity 参数
np.str_
标量现在支持缓冲区协议
numpy.copy
的 subok
选项
numpy.linalg.multi_dot
现在接受一个 out
参数
numpy.count_nonzero
的 keepdims
参数
numpy.array_equal
的 equal_nan
参数
np.float64
时,使用 AVX512 内部实现 np.exp
numpy.einsum
在下标列表中接受 NumPy int64
类型
np.logaddexp2.identity
被改为 -inf
__array__
的额外参数处理
numpy.random._bit_generator
移动到 numpy.random.bit_generator
pxd
文件提供对随机分布的 Cython 访问
numpy.random.multivariate_normal
中的 eigh
和 cholesky
方法
MT19937.jumped
中的跳转实现
numpy.random
中添加多变量超几何分布np.fromfile
和 np.fromstring
将在错误数据上报错
ma.fill_value
中废弃非标量数组作为填充值
PyArray_As1D
、PyArray_As2D
np.alen
numpy.ma.mask_cols
和 numpy.ma.mask_row
的 axis
参数已废弃
numpy.lib.recfunctions.drop_fields
不再返回 None
numpy.argmin/argmax/min/max
在数组存在 NaT
的情况下返回 NaT
np.can_cast(np.uint64, np.timedelta64, casting='safe')
现在为 False
numpy.random.Generator.integers
更改随机变量流
datetime64
、timedelta64
添加更多的 ufunc 循环
numpy.random
中的模块已移动
PyDataType_ISUNSIZED(descr)
现在对结构数据类型返回 False*.pxd
cython 导入文件
expand_dims
--f2cmap
选项
argwhere
现在对 0d 数组产生一致的结果
random.permutation
和random.shuffle
添加axis
参数
np.random.multivariate_normal
的method
关键字参数
numpy.fromstring
添加复数支持
axis
不为None
时,numpy.unique
具有一致的轴顺序
numpy.matmul
的布尔输出现在转换为布尔值
2**32
时,numpy.random.randint
产生了不正确的值](release/1.18.0-notes.html#numpy-random-randint-produced-incorrect-value-when-the-range-was-2-32)
numpy.fromfile
添加复数支持
gcc
,则添加std=c99
(release/1.18.0-notes.html#std-c99-added-if-compiler-is-named-gcc)
NaT
现在在数组的末尾排序
np.set_printoptions
中的不正确threshold
引发TypeError
或ValueError
numpy.distutils
对 LDFLAGS 和类似的值进行了更改](release/1.18.0-notes.html#numpy-distutils-append-behavior-changed-for-ldflags-and-similar)
numpy.random.entropy
-Werror
构建
numpy.polynomial
函数中传递 float
时将发出警告](release/1.17.0-notes.html#numpy-polynomial-functions-warn-when-passed-float-in-place-of-int)
numpy.distutils.exec_command
和 temp_file_name
](release/1.17.0-notes.html#deprecate-numpy-distutils-exec-command-and-temp-file-name)
numpy.nonzero
](release/1.17.0-notes.html#numpy-nonzero-should-no-longer-be-called-on-0d-arrays)
numpy.broadcast_arrays
的结果将发出警告](release/1.17.0-notes.html#writing-to-the-result-of-numpy-broadcast-arrays-will-warn)
float16
亚正常值舍入](release/1.17.0-notes.html#float16-subnormal-rounding)
MaskedArray.mask
现在返回掩码的视图,而不是掩码本身
numpy.frombuffer
中查找 __buffer__
属性](release/1.17.0-notes.html#do-not-lookup-buffer-attribute-in-numpy-frombuffer)
take
, choose
, put
中覆盖缓冲区会发出警告](release/1.17.0-notes.html#out-is-buffered-for-memory-overlaps-in-take-choose-put)
i0
现在总是返回与输入相同形状的结果](release/1.17.0-notes.html#i0-now-always-returns-a-result-with-the-same-shape-as-the-input)
can_cast
不再假定所有的不安全转换都被允许](release/1.17.0-notes.html#can-cast-no-longer-assumes-all-unsafe-casting-is-allowed)
ndarray.flags.writeable
的标志位现在更频繁地被切换为真](release/1.17.0-notes.html#ndarray-flags-writeable-can-be-switched-to-true-slightly-more-often)
npy_intp const*
现在会传递维度或步幅输入参数](release/1.17.0-notes.html#dimension-or-stride-input-arguments-are-now-passed-by-npy-intp-const)numpy.random
模块,带有可选择的随机数生成器
ufunc.reduce
及相关函数现在接受一个where
掩码
packbits
和unpackbits
接受一个order
关键字
unpackbits
现在接受一个count
参数
linalg.svd
和linalg.pinv
在厄米矩阵输入上可能更快
timedelta64
操作数
fromfile
现在带有一个offset
参数
pad
的新模式“empty”
empty_like
及相关函数现在接受一个shape
参数
as_integer_ratio
以匹配内置浮点数
dtype
对象可以使用多个字段名称进行索引
.npy
文件支持 Unicode 字段名称
fft
模块
numpy.ctypeslib
中对ctypes
支持进一步改进
numpy.errstate
现在也是一个函数装饰器
numpy.exp
和numpy.log
在 float32 实现中提速
numpy.pad
性能
numpy.interp
更稳定地处理无限值
fromfile
,tofile和ndarray.dump
的Pathlib
支持
isnan
,isinf
和isfinite
ufuncs
isfinite
支持datetime64
和timedelta64
类型
nan_to_num
添加了新的关键字
MemoryErrors
现在更具描述性
floor
,ceil
和trunc
现在尊重内置魔术方法
quantile
现在适用于fraction.Fraction和decimal.Decimal
对象
matmul
中支持对象数组
median
和percentile
函数族不再对nan
发出警告
timedelta64 % 0
的行为调整为返回NaT
__array_function__
覆盖
lib.recfunctions.structured_to_unstructured
不会消除单字段视图。
clip
现在在底层使用 ufunc
__array_interface__
偏移现在按文档所述工作
force zip64
标志中savez
的pickle
协议设置为3
KeyError
而不是ValueError
。
matmul (*@* operator)
与对象数组一起使用。numpy.lib.recfunctions.structured_to_unstructured
不会压缩单字段视图__array_interface__
offset 现在按照文档工作timedelta64
操作数的divmod
操作np.ctypeslib
中的ctypes
支持
timedelta64 % 0
的行为已经调整为返回NaT
np.unravel_index
现在接受 shape
关键字参数
histogram
添加了积分平方误差(ISE)估计器
np.loadtxt
现在新增max_rows
关键字参数
np.timedelta64
操作数现在支持取模运算符
randint
和 choice
现在可以用于空分布
linalg.lstsq
, linalg.qr
, 和 linalg.svd
现在可以使用空数组进行计算
numpy.angle
和 numpy.expand_dims
现在适用于 ndarray
子类
NPY_NO_DEPRECATED_API
编译器警告抑制
np.diff
添加了 kwargs prepend
和 append
np.clip
和 clip
方法检查内存重叠
np.polyfit
中选项 cov
的新值 unscaled
__module__
属性现在指向公共模块
np.block
用于大数组
np.take
ndpointer.contents
成员
matmul
现在是一个ufunc
linspace
,logspace
和 geomspace
的起始和停止数组
positive
现在将引发弃用警告
NDArrayOperatorsMixin
现在实现了矩阵乘法
np.polyfit
中方差矩阵的缩放方式已更改
maximum
和minimum
不再发出警告
getfield
有效性检查扩展
__array_function__
重载
writeable
np.savez
返回的NpzFile
现在是collections.abc.Mapping
nditer
__array_interface__
对 ctypes
进行修改(release/1.15.0-notes.html#numpy-no-longer-monkey-patches-ctypes-with-array-interface)
np.ma.notmasked_contiguous
和 np.ma.flatnotmasked_contiguous
总是返回列表(release/1.15.0-notes.html#np-ma-notmasked-contiguous-and-np-ma-flatnotmasked-contiguous-always-return-lists)
np.squeeze
恢复了不能处理 axis
参数的对象的旧行为(release/1.15.0-notes.html#np-squeeze-restores-old-behavior-of-objects-that-cannot-handle-an-axis-argument)
.item
方法现在返回一个字节对象(release/1.15.0-notes.html#unstructured-void-array-s-item-method-now-returns-a-bytes-object)
copy.copy
和 copy.deepcopy
不再将 masked
转换为数组(release/1.15.0-notes.html#copy-copy-and-copy-deepcopy-no-longer-turn-masked-into-an-array)
npy_get_floatstatus_barrier
和 npy_clear_floatstatus_barrier
(release/1.15.0-notes.html#new-functions-npy-get-floatstatus-barrier-and-npy-clear-floatstatus-barrier)
PyArray_GetDTypeTransferFunction
的更改(release/1.15.0-notes.html#changes-to-pyarray-getdtypetransferfunction)
np.gcd
和 np.lcm
ufuncs 已添加整数和对象类型
np.intersect1d
添加了 return_indices
关键字(release/1.15.0-notes.html#return-indices-keyword-added-for-np-intersect1d)
np.quantile
和 np.nanquantile
(release/1.15.0-notes.html#np-quantile-and-np-nanquantile)
np.einsum
的更新(release/1.15.0-notes.html#np-einsum-updates)
np.ufunc.reduce
和相关函数现在接受初始值
np.flip
可以在多个轴上操作(release/1.15.0-notes.html#np-flip-can-operate-over-multiple-axes)
histogram
和 histogramdd
函数已移动到 np.lib.histograms
(release/1.15.0-notes.html#histogram-and-histogramdd-functions-have-moved-to-np-lib-histograms)
histogram
将接受 NaN 值(release/1.15.0-notes.html#histogram-will-accept-nan-values-when-explicit-bins-are-given)
histogram
在给定明确的 bin 边界的情况下适用于日期时间类型
histogram
“auto” 估计器更好地处理有限的方差
histogramdd
返回的边界现在与数据浮点类型匹配
histogramdd
允许在一部分轴上给出明确的范围
histogramdd
和 histogram2d
的 normed 参数已更名
np.r_
在 0d 数组上可用,而 np.ma.mr_
在 np.ma.masked
上可用
np.ptp
接受 keepdims
参数和扩展的轴元组
MaskedArray.astype
现在与 ndarray.astype
相同
nan_to_num
在接收标量或 0d 输入时总是返回标量
np.flatnonzero
在可转换为 numpy 类型上起作用
np.interp
返回 numpy 标量而不是内置标量
dtype=object
,覆盖默认的 bool
sort
函数接受 kind='stable'
linalg.matrix_power
现在可以处理矩阵堆栈
random.permutation
的性能提高
axes
、axis
和 keepdims
参数
float128
值现在在 ppc 系统上正确打印出来](release/1.15.0-notes.html#float128-values-now-print-correctly-on-ppc-systems)
np.take_along_axis
和 np.put_along_axis
函数
np.ma.masked
不再可写
np.ma
函数产生的 fill_value
发生了变化
a.flat.__array__()
当 a
非连续时返回不可写数组
np.tensordot
现在在收缩零长度维度时返回零数组
numpy.testing
重新组织
np.asfarray
不再通过 dtype
参数接受非数据类型
np.linalg.norm
保留浮点输入类型,甚至对于任意阶数
count_nonzero(arr, axis=())
现在计算没有轴,而不是所有轴
test
目录添加了 __init__.py
文件
.astype(bool)
现在对每个元素调用bool
MaskedArray.squeeze
永远不会返回np.ma.masked
can_cast
的第一个参数由from
重命名为from_
isnat
当传入错误类型时引发TypeError
dtype.__getitem__
当传入错误类型时引发TypeError
__str__
和__repr__
UPDATEIFCOPY
数组替代方案nose
插件可被numpy.testing.Tester
使用
parametrize
装饰器添加到numpy.testing
chebinterpolate
函数添加到numpy.polynomial.chebyshev
sign
选项添加到np.setprintoptions
和np.array2string
hermitian
选项添加到np.linalg.matrix_rank
threshold
和edgeitems
选项添加到np.array2string
concatenate
和stack
增加了一个out
参数
random.noncentral_f
中的分子自由度只需为正值
np.einsum
变体释放了 GIL
f2py
现在处理零维数组
numpy.distutils
现在支持同时使用 MSVC 和 mingw64-gfortran
np.linalg.pinv
现在适用于堆叠矩阵
numpy.save
将数据对齐到 64 字节而不是 16
np.lib.financial
中支持 decimal.Decimal
void
类型的元素现在以十六进制表示](release/1.14.0-notes.html#void-datatype-elements-are-now-printed-in-hex-notation)
void
数据类型的打印样式现在可以独立自定义
np.loadtxt
的内存使用量减少
np.set_string_function
影响
array2string
的 style
参数已弃用
RandomState
需要一个一维数组
MaskedArray
对象显示更有用的 repr
np.polynomial
类的 repr
更加明确
ndarray
子类中不再需要 __getslice__
和 __setslice__
...
(省略号)索引 MaskedArrays/常量现在返回 MaskedArray
PyArray_MapIterArrayCopyIfOverlap
添加到 NumPy C-API
__array_ufunc__
positive
通用函数
divmod
通用函数
np.isnat
通用函数测试 NaT 特殊的日期时间和时间间隔值
np.heaviside
通用函数计算 Heaviside 函数
np.block
函数创建块数组
isin
函数,对 in1d
进行改进
unique
的 axes
参数
np.gradient
现在支持非均匀间隔的数据
apply_along_axis
中支持返回任意维度的数组
dtype
添加.ndim
属性以补充.shape
的属性.ndim
(维数).shape
packbits
和unpackbits
进行了性能改进
ndarray
子类的更好默认 repr
linalg
操作现在接受空向量和矩阵
np.hypot.reduce
和np.logical_xor
的reduce
在更多情况下允许
repr
argsort
使用与sort
相同的默认参数
average
现在保留子类
array == None
和array != None
进行逐元素比较
np.equal, np.not_equal
对对象数组忽略对象身份
np.random.multivariate_normal
处理糟糕协方差矩阵的行为
assert_array_less
现在比较np.inf
和-np.inf
assert_array_
和屏蔽数组的 assert_equal
会隐藏更少的警告
memmap
对象中的 offset
属性值
np.real
和 np.imag
对于标量输入返回标量
data
属性的赋值
linspace
中 num 属性的 int 强制转换不安全
binary_repr
的位宽参数不足
power
和 **
对于整数的负指数会引发错误
np.percentile
的 “midpoint” 插值方法修复了精确索引的问题
keepdims
关键字参数传递给用户类方法
bitwise_and
的身份变化
assert_almost_equal
更加一致
NoseTester
行为](release/1.12.0-notes.html#nosetester-behaviour-of-warnings-during-testing)
assert_warns
和 deprecated
修饰符更具体](release/1.12.0-notes.html#assert-warns-and-deprecated-decorator-more-specific)
as_strided
rot90
的 axes
关键字参数](release/1.12.0-notes.html#axes-keyword-argument-for-rot90)
flip
numpy.distutils
中的 BLIS 支持](release/1.12.0-notes.html#blis-support-in-numpy-distutils)
numpy/__init__.py
中运行特定于分发的检查的钩子](release/1.12.0-notes.html#hook-in-numpy-init-py-to-run-distribution-specific-checks)
nancumsum
和 nancumprod
函数](release/1.12.0-notes.html#new-nanfunctions-nancumsum-and-nancumprod-added)
np.interp
现在可以插值复数值
polyvalfromroots
](release/1.12.0-notes.html#new-polynomial-evaluation-function-polyvalfromroots-added)
geomspace
](release/1.12.0-notes.html#new-array-creation-function-geomspace-added)
ma.convolve
和 ma.correlate
](release/1.12.0-notes.html#new-masked-array-functions-ma-convolve-and-ma-correlate-added)
float_power
ufunc](release/1.12.0-notes.html#new-float-power-ufunc)
np.loadtxt
现在支持单个整数作为 usecol
参数](release/1.12.0-notes.html#np-loadtxt-now-supports-a-single-integer-as-usecol-argument)
histogram
的改进自动化 bin 估计器](release/1.12.0-notes.html#improved-automated-bin-estimators-for-histogram)
np.roll
现在可以同时滚动多个轴
ndarrays
实现的 __complex__
方法](release/1.12.0-notes.html#the-complex-method-has-been-implemented-for-the-ndarrays)
pathlib.Path
对象现在支持
np.finfo
新增 bits
属性
np.vectorize
新增 signature
参数
numpy.sctypes
现在也包括 Python3 中的 bytes](release/1.12.0-notes.html#numpy-sctypes-now-includes-bytes-on-python3-too)
bitwise_and
的标识已更改](release/1.12.0-notes.html#id1)
np.einsum
中的操作顺序优化
ediff1d
改进了性能和子类处理
ndarray.mean
的精度改进
linalg.norm
返回类型更改
TypeError
而不是 ValueError
%
和 //
运算符
np.gradient
现在支持axis
参数
np.lexsort
现在支持带有对象数据类型的数组
np.ma.core.MaskedArray
现在支持order
参数
ndarray.tofile
现在在 Linux 上使用 fallocate
A.T @ A
和A @ A.T
的操作的优化
np.testing.assert_warns
现在可以作为上下文管理器使用
numpy.distutils
中已删除对 Pyrex 的支持
np.broadcast
现在可以使用单个参数调用
np.trace
现在尊重数组子类
np.dot
现在引发TypeError
,而不是ValueError
linalg.norm
返回类型更改
testing
命名空间中的随机数生成器
MaskedArray
的切片/视图赋值numpy.i
中的 swig bug
axis=0
之外的任何方向上的 1 维数组的连接会引发 IndexError
max_rows
参数
fweights
和aweights
参数
norm
pad_width
和constant_values
的更多输入类型
out
参数
float.hex
方法产生的字符串
promote_types
and string dtype
can_cast
and string dtype
doc/swig
directory moved
npy_3kcompat.h
header changed
sq_item
and sq_ass_item
sequence methods
zeros_like
for string dtypes now returns empty strings
np.linspace
和np.logspace
添加了 dtype 参数
np.triu
和np.tril
广播更加通用
tobytes
方法的别名为tostring
numbers
模块兼容性
np.vander
添加了increasing
参数
np.unique
添加了unique_counts
参数
np.cross
支持全广播
np.partition
为基础的实现中实现
np.array
性能提升
np.searchsorted
性能提升
np.random.multivariate_normal
中的协方差检查
select
输入项废弃
rank
函数
numpy.core
numpy.lib
numpy.distutils
numpy.random
numpy.f2py
numpy.poly
numpy.f2py
中 size 函数的支持
默认错误处理
numpy.distutils
numpy.testing
C API
numpy.fft
numpy.memmap
numpy.lib
numpy.ma
numpy.distutils