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

Question

The documentation code with the problem is at the beginning of a method:

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

The warnings are:

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.

What can be done to remove these warnings and their cause(s)?

score 33 · Accepted Answer · answered Aug 25 '17 at 11:27

Just add a blank line after the summary description of the method, before the description of the parameters:

"""
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 you can find this advice:

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.

score 10 · Answer 2 · answered Dec 07 '20 at 19:18

Maybe this will help somebody who stumbles upon this question - in my case I was getting a bunch of warnings that were because I was using Google style docstrings. Just add "sphinx.ext.napoleon" to the extensions list in conf.py and the warnings should go away.

score 4 · Answer 3 · answered Apr 03 '21 at 11:07

You might also want to try to put the sphinx.ext.napoleon at the very top of the extensions, i.e.

do ** this**

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

and not this

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

worked for me

score 1 · Answer 4 · answered Jul 22 '21 at 19:52

The sphinx/rst directive you are using expects the content to have a single line of data. To fix this, add an extra indentation (tab) before the data and then you can break the data into multiple lines without error.

For example, the note directive expects a single line of content.

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

However,

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

4 Answers4