生成代码文档时如何消除意外缩进警告的原因？

Posted 2023-02-16

【中文标题】生成代码文档时如何消除意外缩进警告的原因？

【英文标题】：How to remove the cause of an unexpected indentation warning when generating code documentation?

【发布时间】：2018-02-03 10:36:23

【问题描述】：

有问题的文档代码在方法的开头：

"""
Gtk.EventBox::button-release-event signal handler.
:param widget: The clicked widget (The Gtk.EventBox).
:param event: Gdk.EventButton object with information regarding
       the event.
:param user_data: The Gtk.LinkButton that should be opened when
       the Gtk.EventBox is clicked.
:return: None
"""

警告是：

C:/msys64/home/hope/python+gtk/test/main.py:docstring of main.Builder.advertisem
ent_clicked:4: WARNING: Unexpected indentation.
C:/msys64/home/hope/python+gtk/test/main.py:docstring of main.Builder.advertisem
ent_clicked:5: WARNING: Block quote ends without a blank line; unexpected uninde
nt.

可以做些什么来消除这些警告及其原因？

【参考方案1】：

您使用的 sphinx/rst 指令要求内容包含单行数据。要解决此问题，请在数据前添加一个额外的缩进（制表符），然后您可以将数据分成多行而不会出错。

例如，note 指令需要一行内容。

.. note::
    
    single line note expected
    this line cause error

然而，

.. note::

        adding extra indent solves the problem
        we can add more lines without error
        and so on

【参考方案2】：

您可能还想尝试将sphinx.ext.napoleon 放在扩展程序的最顶部，即

做**这个**

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",
    # ...
]

而且不是这个

extensions = [
    "sphinx.ext.autodoc",
    # ...
    "sphinx.ext.napoleon",
]

为我工作

【参考方案3】：

也许这会对偶然发现这个问题的人有所帮助 - 就我而言，我收到了一堆警告，因为我使用的是 Google 样式的文档字符串。只需将“sphinx.ext.napoleon”添加到 conf.py 中的 extensions 列表中，警告就会消失。

【讨论】：

谢谢杰瑞。

【参考方案4】：

只需在方法的摘要描述之后，参数的描述之前添加一个空行：

"""
Gtk.EventBox::button-release-event signal handler.

:param widget: The clicked widget (The Gtk.EventBox).
:param event: Gdk.EventButton object with information regarding
       the event.
:param user_data: The Gtk.LinkButton that should be opened when
       the Gtk.EventBox is clicked.
:return: None
"""

Here你可以找到这个建议：

如果您收到“意外缩进”的 Sphinx 构建错误，它 可能是因为 Sphinx 需要一个空行，例如在 文字文本块。您的线路可能已经包裹和混淆了 Sphinx。在 在这种情况下，请尝试将文本拉到上一行，即使它 超出窗口的边缘。或者，您可以按 Enter 转到下一行，但请务必在新行上缩进文本。