狮身人面像意外的部分标题 - numpydoc答案

【问题标题】：Sphinx Unexpected section title - numpydoc狮身人面像意外的部分标题 - numpydoc
【发布时间】：2016-02-12 15:06:09
【问题描述】：

我无法使用 numpy 格式使 Sphinx 正常工作。我正在使用这个example 进行测试，正在执行“make html”，但是我收到了几个警告来识别参数、注释、返回等。例如：

SEVERE: Unexpected section title.
ERROR: Unexpected indentation.
also
WARNING: Inline emphasis start-string without end-string.
WARNING: Literal block expected; none found

这个问题已经被问过了，但是我搜索并尝试了几个小时没有成功。

到目前为止我做了什么：

已安装 Sphinx v1.3.5
将numpydoc更新到0.5版
将扩展名numpydoc、sphinxcontrib.napoleon 和sphinx.ext.napoleon 添加到conf.py 文件中。
试过rst2html docum.txt docum.html
因为我认为它没有使用 numydoc，所以我写了一个不正确的名称作为扩展名，它给出了一个错误（应该是这样，所以我认为它正在识别 numpydoc）。
已将numpydoc_show_class_members = False 添加到conf.py
删除整个之前的 html 输出

有什么建议或提示有什么问题吗？我可以尝试什么？

谢谢

【问题讨论】：

欢迎使用 stackoverflow。告诉我们更多您尝试的其他方法，您会得到与您阅读过的相同的建议
每当我遇到这样的问题时，都会缩进一两个我没有看到的空格。或者，我忘记了一些换行符。有行号吗？另一个想法：使用二进制搜索。注释掉一半的文档，看看问题仍然存在。找出问题出在哪一半，然后继续尝试，直到将问题隔离为几行。
嗨。我隔离并修复了每个警告，我真的很惊讶。看起来 Sphinx 无法识别这些部分。我构建的示例是numpydoc文档中提供的示例，问题是：1.代码内部的*被标识为Inline强调，2.文档中“::”（文字块）之后的代码需要缩进，3.那里是部分缩进错误（参数、返回等），4. 我可以在 html 中看到“”“（来自文档）。 python 代码是否需要始终进行调整，还是对我没有好处？
你好，这是我第一次提出问题，我编辑了它，因为如果问题得到更好的解释，回复按钮建议向问题添加信息，而不是在这里回复。回到这个问题，我没有同时使用sphinxcontrib.napoleon 和sphinx.ext.napoleon，但我试图同时解决这两个问题。经过更多测试后，我的问题是：我的 Sphinx 无法识别所有 numpy 样式，例如函数内部的缩进等。我是否应该在弄清楚一些事情之后再提出一个全新的问题并将其留在这里？
谢谢，但我仍然认为问题完全一样，我的新问题可能会使它看起来更好，也许更清楚，但问题与原始问题中描述的相同。

标签： python numpy python-sphinx numpydoc

【解决方案1】：

问题是我使用 numpydoc 直接用.. toctree:: filename 记录模块，但它必须与.. automodule:: filename 一起使用。这里有更多关于如何使用它的信息：http://www.sphinx-doc.org/en/stable/tutorial.html#setting-up-the-documentation-sources。感谢您的帮助。

【讨论】：