Best practices for aliases exposed in multiple public modules

[tlambert03]

hey @pawamoy, i have a question about "Multiple secondary URLs found".

let's say I have a package with a class defined at package.submodule.MyClass, and that class is exported in both package/submodule/__init__.py and re-exported at the top level /package/__init__.py, what is the "proper" way to handle that when autogenerating nav.

I know i can cop-out and use resolve_closest: True. And I also know that I can choose to only expose it in one of the two modules. What I think I really want is for that object to appear in the summary table in the rendered docs for the top level module (package), but have the link resolve to the entry at packages.submodule.MyClass. tips?

[pawamoy]

Hey @tlambert03! Good question. We do recommend exposing objects in unique locations. And we do have requests in the backlog for rendering links to objects rather than re-rendering them, as well as requests to improve summaries. For now there's no particular tip though 😕

Also note that mkdocstrings/griffe#357 is causing a lot of these "Multiple secondary URLs" warnings.

[tlambert03]

First off, that document is amazing 🤩. I will point others to it often. So well written, and the kind of thing that doesn’t get written about enough. Bravo.

I still struggle a bit with the single public location suggestion though I guess 😂. I often use my top module to indicate “here are all the most important objects that you will likely interact with in this library”. I do hide most other modules, but often have one layer of public submodules as you describe for medium size libs. In those cases, I really would rather keep the object as a member of its submodules, because that provides context to what the object does (“ah, this is in models, must relate to models”) in a way that would not be immediately obvious if I just exported everything in a large top level namespace. At the same time, I do often want to indicate some objects as particularly special entry-point objects, and put those at the top namespace. For me, that provides clarity and immediately directs a newcomers eye to the most important bits of the package… (but I don’t want to lose the context by hiding it from the submodule’s init).

anyway, that’s just some random thoughts. From a docs perspective, I think I will likely use resolve_closest for now, but I’m happy to have a better understanding of the principles behind the warnings, and would will keep an eye out for those backlogged issues.

Thanks!

[pawamoy]

Thank you, I've been waiting for such feedback 🥲 Put my heart and experience in these documents!

I still struggle a bit with the single public location suggestion though I guess

No worries, I'm the outlier here with my fully hidden module layout, and I did get complaints that Griffe's API is not easily discoverable since everything is exposed in the top-level module. (I'll stick by it though). So, yes, I'll do everything I can to make lives of devs easier: the multiple secondary URLs warning is too easy to spawn, and I'm considering downgrading it to DEBUG, or another similar solution that will stop bothering devs. Ideally we'd implement the "render exports as links" feature from above instead. The real goal of the warning is to avoid having the same object rendered in multiple locations in the docs, not preventing users from aliasing these objects in the top-level module.

[tlambert03]

No worries, I'm the outlier here with my fully hidden module layout

your rationale is well-defended! so definitely not an "odd" outlier if one at all. And I am sympathetic to the argument that having two import locations has a "smell". But I suppose I'm committed, in a sense, to supporting those multiple locations till-deprecation-do-us-part :)

Put my heart and experience in these documents!

it's very clear. in all the things you do! I posted it on bluesky :)