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

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.

如何消除这些警告及其原因？

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

Here 你可以找到这个建议：

If you get a Sphinx build error that says “Unexpected indentation,” it is probably because Sphinx is expecting a blank line, such as after a literal text block. Your line may have wrapped and confused Sphinx. In this case, try pulling the text up to the previous line even if it extends out past the margin of your window. Or, you could press Enter to go to the next line, but be sure to indent the text on the new line.

Answer 2

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

Answer 3

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

做**这个**

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

并且不是这个

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

对我有用

Answer 4

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

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

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

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

How to remove the cause of an unexpected indentation warning when generating code documentation?

restructuredtext

python-2.7

python-sphinx

msys2

windows-10