sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

Autosummary shows function signature in modules group when importing function of same name

Open aeisenbarth opened this issue 1 year ago • 0 comments

Describe the bug

When importing a function from a module of same name, the module is documented in the group "Modules" but with function signature. This is a problem, because other Sphinx extensions and their options can have unexpected behavior (like not apply correct formatting to the function in the modules group).

How to Reproduce

Example

Assume a project of the following structure:

my_module
├── __init__.py
└── my_process.py

where my_process.py contains a more detailed implementation:

def my_process(*args, **kwargs):
    pass

# and some private functions used by the implementation

which is imported and used in __init__.py:

from my_module.my_process import my_process

def call_my_process(*args, **kwargs):
    my_process(*args, **kwargs)

Sphinx is configured to use autosummary, but ignore imports:

extensions = [
    "sphinx.ext.autosummary",
]

autosummary_generate = True
autosummary_imported_members = False

and index.rst:

.. autosummary::
   :toctree: generated/
   :recursive:

   my_module2

Actual behavior

  • The import is not ignored, but documented.
  • The function is listed in the "Modules" group (with signature!).

image

Expected behavior

  • With autosummary_imported_members=False, the import is not ignored. The function my_process is only documented in the submodule my_module.my_process.
  • With autosummary_imported_members=True, the imported function is listed in the "Functions" group.

Environment Information

Platform:              linux; (Linux-5.15.0-91-generic-x86_64-with-glibc2.35)
Python version:        3.9.17 (main, Jul  5 2023, 20:41:20) 
[GCC 11.2.0])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.16.1

Sphinx extensions

["sphinx.ext.autosummary"]

Additional context

No response

aeisenbarth avatar Feb 21 '24 13:02 aeisenbarth