问题标签 [numpydoc]

使用numpy样式记录 Python 模块并使用sphinx和numpydoc扩展生成 html 文档，我偶然发现了一个关于项目符号列表的错误（或功能？）。

根据reStructuredText 参考，项目符号列表前后需要一个空行。

因此我想知道：为什么第一个版本可以工作（而它不应该），与（不工作的）第二个版本有什么不同？

编辑：

在生成的 html 中，第一个和最后一个版本在外观上有所不同。如果需要没有前导空行的项目符号列表的外观（html 中的空间更少），可以使用快速修复

这避免了解析错误，但仍然没有回答为什么 :-)

我面临与此线程相同的问题。当我构建我的 Sphinx 文档时，make html我会收到很多这样的警告

我正在使用html_theme = 'sphinx_rtd_theme'. 如果我将其更改为classic，那么我不会收到警告。如果我添加numpydoc_show_class_members = False到conf.py，那么我也不会得到它们。

但; 我真的很喜欢sphinx_rtd_theme，当我使用classic或添加时，我的 Python 方法numpydoc_show_class_members = False的“目录”会被删除，我更喜欢保留它（参见图像中的红色框）。

该cars模块的文档由

该模块包含一个Car具有两个方法的类。文档字符串是用numpydoc.

使用 Sphinx 扩展 NumpyDoc，是否有某种方法可以自动确保文档与其记录的代码匹配？

例如，由于拼写错误，以下文档与代码不匹配：

Sphinx 或 NumpyDoc 可以使这成为错误吗？

我正在使用 NumPyDoc 样式的文档字符串来记录 Python 包。我想从'numpydoc' Sphinx 扩展切换到Napoleon，因为我发现它以更紧凑和可读的方式格式化文档字符串。但是，它并没有在文档顶部列出类的方法，这是我发现 numpydoc 的一个非常有价值的特性。有谁知道如何在拿破仑中手动打开它？

我正在做一个需要 Numpy 文档的项目。在我的 Java 时代，我记得在 Eclipse/IDEA 中有检查 Javadoc 遵守情况的 linter；是否有等效的检查 Numpy 文档样式的遵守情况？

我知道 PEP257，但它似乎没有对 Numpy 文档进行任何特定检查。

几天前我开始使用 Sphinx 来记录一个 python 包，我得到了一个似乎很常见的错误，但我找不到解决方案。

我使用 sphinx-quickstart 来设置所有内容。我使用“doc/”作为文档根位置。包含我的包的文件夹设置为：

快速启动后，我将 conf.py 中的路径编辑为：

然后我将包中的一个脚本添加到 index.rst 以查看 sphinx 的工作原理。

我得到的错误代码：

我尝试过的解决方案：

1. 将 sphinx.ext.napoleon 添加到扩展列表中，因为我所有的文档字符串都是使用 numpy 格式编写的。错误并没有消失。我还将拿破仑扩展名放在 autodoc 之后，因为其中一个帮助页面建议这样做。

   扩展 = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

2. 将 numpydoc_show_class_members = False 添加到 conf.py。我把它直接放在扩展下面。这也没有帮助。

3. 文件夹位置的几种不同配置。我还尝试将根位置设置为 myfolder 并将源设置为 mypackage 并将构建设置为 doc。没有一个有效。

你有什么想法可以帮助我吗？

我的 pytest.ini 目前看起来像这样：

所以我已经测试了 PEP8。但我也想测试 numpydoc 格式的文档字符串：

• 所有参数的命名顺序是否正确？
• 如果有返回语句，文档字符串中是否也有Returns？
• ...

这可能吗

我正在按照 numpy 文档字符串指南编写我的文档字符串。然后我使用 sphinx 的 autodoc 来生成我的文档。在一些文档字符串中，我使用了 LaTeX 公式（sphinx.ext.mathjax）。这似乎\r意味着一些特别的东西，比如一条新线。如果我有以下命令：

它没有正确渲染。它将角度换成新行并给我一个错误：内联解释文本或短语参考起始字符串没有结束字符串 如果我用 \langle 替换 \rangle 一切正常。我怎样才能解决这个问题？

我正在使用 sphinx autodoc 将我的文档字符串翻译成一个不错的文档页面。在文档字符串中，我通过使用 sphinx 拿破仑扩展来遵循 numpy 的文档字符串指南。我想知道以下几点：如果我有一个等式

自动文档无法识别:label:. 我的格式是否错误，或者 autodoc/mathjax/napoleon 无法处理方程式中的标签？

我将 sphinx autodoc 扩展与 sphinx.ext.napoleon 一起使用。我正在关注 numpydoc 样式指南，因为我认为它比 google 的更具可读性。但是，我注意到以下我无法解决的问题。

我有以下问题。是否可以在参数部分（或返回等）中允许有一个列表？我想要类似的东西：

更新根据史蒂夫皮尔西的回答，我已经删除了一些初始问题。这是python文件：

不幸的是，这仍然给出了“这将是……”的字体太大并且没有放在param_1as for旁边的问题param_2：

如果我删除项目符号列表，我会得到一个外观正确的输出。将上面的代码更改为：

这导致以下正确的输出：

生成文档的 .rst 文件很简单：

如果我使用 numpydoc 而不是 sphinx.ext.napleon 似乎我得到了正确的输出：

至少“pandas data frame”和“This....”的字体是一样的。但是我更喜欢拿破仑风格，一切都更小，一开始没有灰线。

最后，在项目符号点之前删除空行也无济于事。它使情况变得更糟：