warnings created from derived classes when constructor has no docstring

[TheFriendlyCoder]

We recently ran into a subtle but reproducible problem generating api docs for some of our projects. The problem case is as follows.

1. Create a base class with a constructor, and provide both a class doc string and a constructor doc string, something like this:

class MyBase:
    """Base class docstring"""

    def __init__(self, fubar):
        """
        Args:
            fubar (str):
                parameter description here
        """

2. Create a derived class that has an overloaded constructor, with no doc string, something like this:

class MyDerived(MyBase):
    def __init__(self):
        pass

3. Enable the auto content option in Sphinx to combine the class doc string and constructor doc strings together (ie: autoclass_content = "both")

4. Attempt to generate the docs using the apidoc extension.
   Expected behavior: the API docs for both the base and derived classes should be generated without warnings.
   Actual behavior: docs for the base class generate correctly, but docs for the derived class produce the following warning
   "docstring of sample.MyDerived: WARNING: Unexpected indentation."

This is a rather insidious warning because it points the developer to the derived class as the root cause of the problem, but there is no obvious correlation between the code of the derived class and the actual cause of the problem. This is further exacerbated when the derived class is in a different project or library from the base class, because then the developer needs to review the contents of the full inheritance stack. However, even after reviewing the code for the base class (which may or may not be the direct parent class of the one exposing the error) there is no obvious correlation between the warning and the code because the doc strings on the base class(es) are defined and correctly formatted, and Sphinx/apidoc do not complain when generating the docs for the base class.

After much ad-hoc testing I was able to deduce that simply adding a doc string to the constructor on the derived class was sufficient to circumvent the error, but when working on a large number of Python projects and sharing those projects across many developers, problems like this are hard to avoid in practice.

My team manages dozens of Python projects, and are trying to build docs for all without having any warnings produced, so we've opted to disable the combined auto content flag to avoid these superfluous warnings. However, this is just a hack/workaround to get us by for now. I hope someone can investigate the root cause of this problem and fix it so that docs for derived classes can be generated without warnings.

[TheFriendlyCoder]

Oh, and we are using the latest version of Sphinx (4.0.1) and the apidocs plugin (0.3.0) when testing. Also, as is evidenced by the example code, we are using the Google style doc strings as supported by the napoleon extension provided by Sphinx as well.

I also took some time to do some additional testing across several different versions of Sphinx, and was able to reproduce this problem as far back as v2.2.0. It is possible that older version of Sphinx may have provided similar results as well. So this appears to be a long standing bug, which I'm surprised hasn't been reported or fixed yet.

[TheFriendlyCoder]

Pretty sure I've reported this bug in the wrong project. I've reworked this into a bug report for Sphinx, under the autodocs extension here: sphinx-doc/sphinx#9250