Search code examples
pythonpython-sphinxdocstring

Unexpected unindent python-sphinx

I have the following docString in my python project:

def challenge():
    """Route for POST a challenge.

    For call this route, we need to pass a serialNumber on body form.
    If this serialNumber is in the database and corresponds to a tablet we call methods for create challenge

    :returns: An HTTP response with a challenge

    EXAMPLE::
        REQUEST
            curl --location --request POST 'xxxx:xxxx/challenge'
            --form 'serialNumber="xxxxx"'
        RESPONSE
            {
                "challenge": "xxxx"
            }

    """

When I run make html, sphinx give me the following error:

docstring of src.modules.challenge.router.challenge:15: WARNING: Definition list ends without a blank line; unexpected unindent.

And the formatting is not at all what I want in my documentation. I want for each route of my API to insert an example of request / response in the form of text block or code block.

Solution

  • Add a blank line between EXAMPLE:: and REQUEST.

    Blocks (paragraphs) must be separated from other blocks by blank lines. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks.