Problems with doc comments using Generic class and extending it

[thepabloaguilar]

Describe the bug

This is a very specific bug (I think), when we have a Generic class with doc comment for an attribute and I extend it. If the child class has the __init__ method (using typed parameters) and I try to reassign the attribute from Generic class I got the following error:

WARNING: :1: (WARNING/2) Field list ends without a blank line; unexpected unindent.

To Reproduce
Steps to reproduce the behavior:

$ git clone git@github.com:dry-python/returns.git
$ cd returns
$ poetry install
$ cd docs
$ poetry run make html

Code example:

• Python script

from typing import (
    ClassVar,
    Type,
    TypeVar,
    Generic,
)

_ValueType = TypeVar('_ValueType')


class MyGeneric(Generic[_ValueType]):
    #: Doc comment example.
    some_type: ClassVar[Type['MyGenericChild']]


class MyGenericChild(MyGeneric[_ValueType]):
    def __init__(self, inner_value: _ValueType) -> None:
        pass


MyGeneric.some_type = MyGenericChild

• rst

.. test:

Test
====

.. automodule:: lib.test
   :members:

If you try to modify something in the script maybe the error will not appear, it's a very specific corner case!

Expected behavior

The warning should not appear!

Your project

returns

Environment info

• OS: Linux 5.7.9-1-MANJARO
• Python version: 3.8.3
• Sphinx version: 3.1.1
• Sphinx extensions:

sphinx.ext.autodoc
sphinx.ext.doctest
sphinx.ext.todo
sphinx.ext.coverage
sphinx.ext.viewcode
sphinx.ext.autosummary
sphinx.ext.napoleon
m2r
sphinx_autodoc_typehints
sphinxcontrib.mermaid
hoverxref.extension

---

related issue dry-python/returns#568

[tk0miya]

I passed -vv option to the Makefile and confirm what happened in the build. As a result, the following reST code is generated during the build:

.. py:attribute:: ReaderFutureResult
   :module: returns.context.requires_context_future_result

   Sometimes `RequiresContextFutureResult` is too long to type.

   :param inner_value:
   :type inner_value: :py:data:`~typing.Callable`\[\[\-_EnvType], :py:class:`~returns.future.FutureResult`\[\+_ValueType, \+_ErrorType]]
   alias of :class:`returns.context.requires_context_future_result.RequiresContextFutureResult`

Surely, additional blank line is needed just after the field list. I guess this field list is generated by sphinx_autodoc_typehints extension. Actually, no warnings are shown when I disabled it. I think this is not a bug of Sphinx itself.

[thepabloaguilar]

Thanks for your answer!! I'll open an issue on sphinx_autodoc_typehints, seems the bug is there.

[thepabloaguilar]

After read sphinx_autodoc_typehints code I think the problem is here with autodoc! All of the problems is because that last line contains:

alias of :class:`returns.context.requires_context_future_result.RequiresContextFutureResult`

So, that line isn't generated by sphinx_autodoc_typehints. autodoc is inserting that line without any validation.

[thepabloaguilar]

We can verify if the last line contains something before inserting a new one!

[tk0miya]

autodoc expects the extensions to return docstring ends with a blank line (silently). But I noticed it can be adjusted from our side. And I think no silent rule is needed for this case. Okay, I'll fix this on next release.