Docs from global variable that points to class with special members don't appear

[maehster]

Describe the bug
I am not sure if this is a bug or I am doing something wrong :)

But when I have the code below, the docstring of initialize won't appear in my doc html.

Surprisingly, the initialize method will appear in the docs when I remove the __call__ method from the class.

To Reproduce

from types import SimpleNamespace
from typing import Any


class Container:
    pass


class Initializer:
    def __call__(self, container_name: str, initial_content: Any = SimpleNamespace()):
        setattr(Container, container_name, initial_content)

    def __getattr__(self, container_name: str):
        return lambda initial_content = SimpleNamespace(): setattr(_Container, container_name, initial_content)


initialize = Initializer()
initialize.__doc__ = """
    This is some documentation.
"""

cd docs && \
make clean && \
sphinx-apidoc --force -e -o ./source ../<package> && \
make html

Expected behavior
Docs of initialize should appear in the docs but they do not.

Environment info

Python version: [3.8.5]
Sphinx==3.4.3
sphinx-rtd-theme==0.5.1
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4

extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon']

[felix-hilden]

Without seeing the documentation source it's hard to tell. But if you're using autodoc, make sure to include the special members. I've not used sphinx-apidoc, but it allows for templating, which surely can be used to include the special members. I'm guessing they are quite similar to autosummary templates.

[maehster]

Thanks for answering so fast! My problem is not that the special members don't appear in the html page but that the docstring for the variable initialize doesn't appear. It appears once I remove the __call__ method from Initializer.

So, what I want to have shown on the doc page is the string This is some documentation.. This works as expected when there is only the __get_attr__ method.

Does that help you or can I provide additional information?

[felix-hilden]

I see, the issue title could perhaps be changed then. Now it reads exactly "docs from object getattr and call don't appear", which is not exactly "variable is not documented".

Doesn't help much, since I'm not experienced with apidoc. But documenting module attributes (i.e. variables in the module) is not the same as documenting its classes. Maybe try removing the __doc__ = ... and just have a variable docstring.

initialiser = Initialiser()
"""Initialiser instance."""

The above is interpreted as the docstring for initialiser. Or should at least.

[maehster]

I changed the title. Leaving out the __doc__ leads to the same result.

[felix-hilden]

👍 Maybe somebody more experienced could chime in then 😅 That's pretty much all my guesses.

[maehster]

No worries! Thank you very much :)

[tk0miya]

This is almost the same as #8917. And it has already been fixed. Please wait for the v4.0 release.