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

Question

有问题的文档代码位于一个方法的开头：

"""
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.

有什么方法可以消除这些警告及其原因？

- silviubogan

Answer 1

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

"""
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
"""

这里提供了以下建议：

如果你遇到Sphinx构建错误，提示“意外缩进”，那可能是因为Sphinx需要一个空行，例如在文字块之后。你的一行文本可能会自动换行而让Sphinx困惑。此时，请尝试将该行文本移至上一行，即使它超出了窗口边缘的范围。或者，你可以按Enter键进入下一行，但请确保在新行上缩进文本。

- silviubogan

Answer 2

或许这会对遇到同样问题的人有所帮助——在我的情况下，我收到了许多警告，因为我使用了< strong>谷歌风格的文档字符串。只需将“sphinx.ext.napoleon”添加到conf.py中的extensions列表中，这些警告就会消失。

- jerry_

Answer 3

你可能还想尝试将sphinx.ext.napoleon放在扩展列表的最上面，即：

这样做**会更好**

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

和不是这个

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

对我有用

- Sandro Braun

Answer 4

您正在使用的 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

- AndreGraveler