API reference: namespacing is confusing

[Huite]

As mentioned by @VermeulenPTM:

The handwritten API reference shows:

However, the individual method shows:

So there's a discrepancy between imod.idf.open and imod.formats.idf.open.

I did a little checking, e.g. xarray has the same for e.g. the groupby objects: (https://docs.xarray.dev/en/stable/generated/xarray.core.groupby.DatasetGroupBy.html#xarray.core.groupby.DatasetGroupBy).html#xarray.core.groupby.DatasetGroupBy

[Huite]

Somewhat to my surprise, this only shows up in the I/O methods for us.

My current explanation is that for all the other namespaces, we are importing individual function/classes (i.e. Python objects) via from imod.prepare.regridder import Regridder versus a module via from imod.formats import idf.

[Huite]

This stackoverflow question seems to have the same goal in mind: https://stackoverflow.com/questions/56137571/change-the-name-of-a-module-in-python-sphinxs-autodoc#:~:text=I%20am%20looking%20to%20autodoc%20some%20functions

[Huite]

I've spent roughly an hour in the train on this, with very little to show for it. It is not at all straightforward to configure sphinx here; by far the most straightforward solution is to promote the different format namespaces, i.e. actually making an imod/idf module (which in turn can be a file or a directory with an init). That feels a bit overblown just for documentation.

I see there are some custom templates (why?), perhaps adding a special one for these formats is the most straightforward solution...

Won't fix is valid too...

[JoerivanEngelen]

Yeah this is something that bugged me a bit as well, but I never pursued looking for a fix. Thanks for going through the efforts of trying to find something.

I go for a won't fix, we can re-open or create a new issue if something good pops up.