mkdocstrings/python

bug: Members shadowing a submodule are ignored

Closed this issue · 2 comments

NiklasRosenstein commented

Description of the bug

When a member shadows a submodule, the member seems to be ignored when documenting the module that contains them. Example:

$ tree mymodule
mymodule
├── __init__.py
└── foobar.py
$ cat mymodule/__init__.py
from .foobar import foobar, spam
$ cat docs/docs/api.md
# API Documentation

::: mymodule

This includes renders the documentation for the spam member but not for foobar.

To Reproduce

An MRE including MkDocs config etc. seems a bit high lift, but happy to provide one if you don't have a project handy to reproduce this on.

pawamoy commented

Thanks for the report @NiklasRosenstein! This is also tracked here: mkdocstrings/griffe#222. Basically, it's an early design flaw. Fixing it is not trivial, but planned.

  • ❤️1
pawamoy commented

I'll close this for now (see mentioned issue). We consider name shadowing (even if only partial because Python kinda handles it) a bad practice, and supporting it would add a lot of complexity to Griffe's code base.