问题标签 [numpydoc]

我最近一直在学习 python，当我注意到这段代码引起的以下警告时，我在 Pycharm 中尝试了一些东西：

“Iterable”类没有定义“__getitem__”，因此不能在其实例上使用运算符“[]”。

我注意到在代码中用 'list[int]' 替换 'list' 可以消除警告，但使用 'list of int' 不会（如果我正确理解 numpydoc 指南，这是做事的正确方法）。那么我到底做错了什么？

在numpydoclist文档字符串中键入 a的正确方法是什么。int

int[]例如，这种语法是否有效？

我将 sphinx 与numpydocs,doctest和 scipy 主题一起使用。

在文档字符串中使用.. plot::时，所有图都被创建，除了没有显示它们被调用的位置，它们都移动到文档的末尾。有没有办法强制它内联，而不需要在.rst文件中重写示例？这是我的example.py文件文档字符串的样子：

……

But both are here.

或者，我尝试添加另一种.. plot::方法，但它改变了范围。

使用make htmlwill state时x未定义。

Numpy 文档字符串指南说：

冒号前面必须有一个空格，如果类型不存在则省略。

并举个例子：

另一方面， PEP8字面意思是冒号前的空格是错误的：

我知道这适用于代码，而不适用于文档字符串，但为什么不保持一致呢？

问题

在冒号前加一个空格的动机是什么？

它似乎违反了印刷规则和 python 约定（或至少是直觉）。

我有这个功能

哪里bar有一个函数，它接受两个名为var1and的变量var2并返回一个strobj，什么是正确的 numpydocs 方法来记录这个？

我想到了类似的东西：

我有一个开源包，其中包含许多不同子模块上的类。所有类都有方法fit和transform，并fit_transform从 sklearn 继承。所有类都有跟随 numpydoc 的文档字符串，带有子标题参数、属性、注释、另见和方法，我在其中列出fit和. 我复制一个类的例子：transformfit_transform

在 Sphinx 的 conf.py 中，我包括：

当我使用 构建文档 sphinx-build -b html docs build时，文档构建得非常好，但是每个类我收到 3 个警告，每个方法一个，上面写着：

我已经用尽了我所有的搜索资源，我准备放弃了。有人知道如何防止该警告或如何使狮身人面像不将其打印到控制台吗？

我附上了错误的副本，如果需要，我可以提供指向 repo 的 PR 链接

我有一个项目，其中一些功能以拿破仑 numpy 风格记录。本着 numpyness 的精神，我有一堆属于 class 的函数参数array-like。这是一个例子：

这工作得很好，并且类型包含在没有链接的输出中：

问题是我在每个函数的每一行都收到警告：

我相当确信有一些解决方案。似乎PR #7690以某种方式解决了这个问题，但我在拿破仑或更广泛的 sphinx 文档中的任何地方都找不到有意义的参考“预处理”。

那么如何摆脱警告呢？

我有带有 NumPy 文档字符串的 Python 代码。设法将 Sphinx 用于 API 文档，但是，__init__.py文件中的类未成功记录。

例子：xxx/__init__.py

样品conf.py：

我还编写了一个函数来确保sys.path附加所有必需的依赖项。

sphinx-apidoc下面的命令自动创建了 3 个 rst 文件：source/api/ps.rst, source/api/ps.xxx.rst,source/api/modules.rst

样品source/api/ps.xxx.rst：

make html构建成功，但警告如下：

以空内容呈现的 HMTL 页面。我希望看到__init__.py（上面的示例文件）中记录的文档字符串，但没有发生。

从技术上讲，Sphinx 是否适用于__init__.py文件中的类/方法文档字符串？我应该关注那些在 期间发生的警告make html吗？

感谢任何关于如何配置 Sphinx 以缩小差距的见解。

如果我有一个文件foo.baz.py：

我想按如下方式记录 api：

Quux这给了我一个带有和的自动汇总表Quuux，以及指向包含其完整文档的页面的链接。但是，它需要我明确列出Quuxand Quuux，所以每当我添加一个类时，我都必须手动将它添加到文档中。

相反，我宁愿做这样的事情，并让它自动生成一个基于 的表__all__，以获得与上面完全相同的输出：

但这不起作用，它会生成一个带有单个条目的表，模块baz，通向一个包含所有内容的页面以及一个汇总表。

有没有办法做到这一点？如果它是相关的，我正在使用numpydoc.

这里有很多关于 SO 的问题，询问在使用 sphinx 构建文档时如何避免继承父文档的文档字符串。我有相反的问题：我希望我的类级文档字符串被继承，但这没有发生。

我构建了一个玩具示例来说明问题。两个相关的类是@dataclasses

在这些sphinx-quickstart文件之上，我修改了index.rst类的启动生成，并修改了配置以包括 autodoc、autosummary 和 numpydoc（也尝试了 napoleon 或 None，但都不在子节点上生成文档字符串）。

作为参考，我在 Sphinx 4.1.2 上。

我可以（理论上）将该行添加__doc__ = Foo.__doc__到Bar，这将手动导入文档字符串；但是在我的情况下 Foo 和 Bar 是自动生成的（XML 绑定）。我将不得不修改生成脚本，这只是部分可能，因为它是一个必须接受相应 PR 的上游项目。如果我能在本地解决这个问题会更好（更快）。

任何有关正在发生的事情或如何前进的指示都将受到高度赞赏。