问题标签 [numpydoc]

注意添加后：我终于让 numpydoc 工作了。这也是一个python 2问题。我在上面运行了 2to3，现在它似乎正在工作。

好的，我花了一整天的时间试图让任何 Sphinx 扩展工作，现在希望有人能指出我做错了什么。（对不起，这有点长，但也许更多信息会帮助您快速找到我的方式的错误）。

Sphinx 似乎像宣传的那样工作，但我想使用 NumPy 风格的文档，所以我想我会安装 numpydoc。万一这很重要，我使用的是 Python 3.3（windows 7 上的 winpython 64 位）。我从这里的指示开始，但得到了错误：

谷歌搜索，我发现有些人通过使用numpydoc.numpydoc 无骰子绕过它。我确保所有可能相关的内容都在我的路径中（以及添加到 sphinxconf.py文件中的 sys.path 中）。我什至尝试将 numpydoc 复制到 sphinx 的 ext 文件夹中并相应地更改扩展字符串，但仍然没有运气。

在这一点上，我放弃了 numpdoc 并决定尝试拿破仑。按照安装pip install sphinxcontrib-napoleon说明进行操作，然后就可以了。但是，唉，不，因为拿破仑似乎在 2.x 而不是 3 中（尽管鸡蛋说Sphinx-1.1.3-py3.3.egg-info并且在安装过程中它说它正在安装sphinxcontrib_napoleon-0.2.1-py3.3-nspkg.pth。不过，很多 python 2 代码。我尝试用 2to3 转换它但是然后我得到一个递归太深的错误。

所以，我决定看看我是否能够为 sphinx 安装任何扩展。我基本上是随机选择 findanything。按要求安装它，但它也失败了，这一次是因为 relpath 错误 ( ValueError: path is on mount 'C:', start on mount 'D:')。我想这意味着我的 python 安装在 C 上是不高兴的，但我试图记录的代码（以及我试图运行 sphinx 的位置）在 D 上（并且我正在运行 Windows）。

那么，我是不是碰巧选择了 3 个有问题的扩展程序？或者，如果不是，我做错了什么以及（更重要的是）我怎样才能正确地做这件事才能让它工作？

PS我对Python完全陌生，所以请不要以为我没有犯一个非常愚蠢和基本的错误。

尽管阅读了本教程、这个问题和numpy 文档字符串标准，但我无法让 sphinx autodoc 与 numpy 文档字符串很好地配合使用。

在我的conf.py我有：

在我的文档文件中，我有：

哪里python_file.py有：

当我跑步时，make html我得到ERROR: Unknown directive type "autosummary". 当我添加autosummary到我的extensions因此：

我得到：

按照这个问题的建议，我添加numpydoc_show_class_members = False到我的conf.py.

现在我可以正常运行make html了，但是ParametersandReturns部分不会被解释为 numpydoc 部分。

有没有办法摆脱这种混乱？

根据numpy/scipy 文档功能参数指南中的约定，应按以下方式记录：

如果 type 是一个独特的类型，例如int或str ，这很简单。

现在我希望参数是BaseClass的实例或任何公开相同接口的对象（例如从BaseClass派生的类）。是否有约定如何简明扼要地记录参数x应该公开某个接口（通过派生或鸭子类型）？

我正在尝试使用sphinx（与autodocand结合使用numpydoc）来记录我的模块，但在基本设置之后，运行make html只生成基本的 html，不包含任何文档字符串。我正在运行Python 3.3，项目结构的大纲如下：

__init__.py是空的，在我添加conf.py的目录中docs/sourcesys.path.insert(0, os.path.abspath('../..'))

make html在目录中运行docs会给出以下输出：

那么，我做错了什么？

Numpy 项目为其文档的格式提供了规范，以支持可读性和自动提取（链接）。他们还提供Numpydoc作为 Sphinx 的扩展，以支持提取一些额外的关键字。

在开始为 docutils 编写扩展之前，是否存在一个库来帮助内省现有的文档字符串并识别不符合 Numpy 标准的情况。

想象一个更成熟的库，其中包含大量文档，希望采用 Numpy 文档规范。一种方法是自省库并生成描述文档字符串状态的报告。

这是在开始将其作为 docutils 或 numpydoc 的扩展实现之前的侦察问题。我错过了现有的解决方案还是存在优雅的解决方案？

在尝试为我的 DocStrings 遵循 NumpyDoc 格式时，我似乎无法弄清楚如何告诉用户参数是关键字参数（即指定为SomeFunc(theKeyWordArg=100)与 相对SomeFunc(100)）。

我在网上找到的文档（例如this和this）仅显示示例，例如

对于关键字参数：

但是对于一般情况，这是我在许多函数中定义的：

我应该这样记录它们：

我遇到的问题是我看不到一种明确的方法来告诉用户参数部分中的哪些参数是关键字与非关键字，因此我必须执行以下操作：

所以用户会调用函数来设置x&name像这样：

有没有标准的方法可以在文档字符串中指出哪些参数是关键字，哪些不是？

例如，这不是说清楚的好方法吗？

where:表示它是非关键字（即。SomeFunc(100, 200)）并=表示关键字（即。SomeFunc(100, 200, name="Bob", label="one and two hundred")）

我正在使用 Spyder IDE（Mac OS 上的 v.2.1.11）并编写一些代码，并在为函数编写 DocString（NumpyDoc 格式）时，无法弄清楚为什么 Spyder Object Inspector会在这种奇怪的方式。

对于像下面这样的 Docstring，“ Calc'd by sellmeier ... ”之后的论文参考是indented ，这会导致奇怪的行为：

上面的 DocString 产生以下输出（Spyder“对象检查器”/帮助面板的屏幕截图），在“ MJ Mondry，DI Babic ... ”文本上带有意外的粗体和缩进/列表编号：

删除缩进时，如下所示：

看起来很正常，如下：

这只是 Spyder 中的一个错误，还是其他一些缩进的预期用途？应该如何使用（或不使用）缩进在 Spyder IDE 中生成各种类型的格式（我假设是 NumpyDoc 格式）？我在NumpyDoc 文档页面
上没有看到任何关于缩进和自动列表的讨论。

只是想知道是否有一些有用的未记录的 DocString 功能我可以在这里利用。（另一方面，我确实注意到我可以使用 DocString 中的“参考”部分，我将在某个时候将 Ref 移动到该部分。）

谢谢！

我的版本如下：Spyder v2.1.11, Python 2.7.6, Qt 4.8.4, PyQt4 (API v2) 4.9.6 on Darwin, Mac OS 10.10.2

我无法让 sphinx 为模块创建汇总表。我已添加sphinx.ext.autosummary到我的conf.py文件中，并且正在使用numpydoc. Sphinx 似乎为类的属性和方法创建了汇总表，但它并没有为包含该类的模块创建汇总表。

我创建了一个最小的工作示例（MWE）来测试它。MWE 项目只有一个__init__.pyand which imports generic_module. 的内容generic_module是：

Sphinx 自动文档foo、bar和onetwo. 它还对onetwo. 但是，它不会在页面顶部为generic_module.

我知道我可以添加.. autosummary::到我的generic_module.rst文件中，如此处所述。但是，我必须列出模块上的每个功能才能使其正常工作。我认为autosummary扩展可以为我做到这一点。

Sphinx 中是否有标准或最佳实践来为复合 Python 数据类型提供更准确的规范？例如，我有一个函数返回一个映射dict并正在使用样式。我应该做类似的事情：strstrnumpydoc

或者可能dict of str: str？

对于已知内容类型的列表，我注意到 NumPy 使用格式

对于这个常见用例，是否有标准或最佳实践可以遵循？

假设我有以下以Numpydoc 样式记录的函数，并且文档是使用Sphinx autofunction 指令自动生成的：

我不想将隐藏的参数宣传为我的公共 API 的一部分，但它会显示在我的自动生成的文档中。有什么方法可以告诉 Sphinx 忽略函数的特定参数，或者（甚至更好）使其自动忽略带前导下划线的参数？