DOC: Provide a public place for users to link to our documentation

[phofl]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

...

Documentation problem

Currently, if users/downstream packages want to link to pandas specific docs (e.g. groupby ops and others) they have to specify the path in pandas.core.... This option becomes unavailable after deprecating pandas.core. #55626 linked to pandas.api.typing as a temporary solution for groupby ops, but we should ideally provide a place outside of typing for docs linkage.

cc @rhshadrach

Suggested fix for documentation

See above

[jorisvandenbossche]

I personally agree that for documentation purposes, ideally we have a "path" to link to that is not linked to typing.

To be explicit, I think the classes that we are discussing here (at least the ones that were already moved in #55626) are:

• DataFrameGroupBy, SeriesGroupBy
• Resampler
• Rolling, Expanding, Window, ExponentialMovingWindow

There are a few others exposed in pandas.api.typing like DatetimeIndexResamplerGroupby, but those aren't used in the reference docs, I think.

One option could be to expose them directly in pandas.api instead of in a sub-submodule of it? (so eg pandas.api.DataFrameGroupBy instead of pandas.api.typing.DataFrameGroupBy)
I know at the moment pandas.api only has submodules, and no direct members, so that would be a change. But that would make the reference a bit shorter and remove the "typing" connotation.

Another option could also be to simply add them to the top-level namespace .. Of course, since a user never constructs those objects directly (using the class constructor), it's not very useful to have them their for other purposes than docs/typing, so that's a trade-off on whether that alone is enough for adding to the top-level namespace.

[rhshadrach]

There was early opposition to having these classes in the top namespace in #48577. I do agree with that opposition, but would be okay with them there. I am also okay with where they currently are - pandas.api.typing is a bit odd for the URL, but I don't see it as problematic.

pandas.api seem like a reasonable location. But it's been mentioned (#48577 (comment)) that if we had clear public modules, then there is no reason for pandas.api. Of course, that doesn't mean it has to be removed.

[jorisvandenbossche]

But it's been mentioned (#48577 (comment)) that if we had clear public modules, then there is no reason for pandas.api

I would say: "there is no reason for pandas.api submodules" (eg pandas.api.typing could just be pandas.typing). But we could still use the pandas.api module itself to expose some things.
I think the main problem for the objects we are discussing here, if we want to put them in a public pandas.<.something.> submodule, what to name that? It are public APIs in terms of that users work with those objects (get them returned, call methods on them), but since you don't call them directly they don't necessarily need to be top-level. But for a submodule, I can't directly think of a good name that would fit for all of those objects together (eg pandas.groupby would also be a bit strange for Window). And then a general "api" for public user-facing API that doesn't need to be top-level might actually make sense?

(personally, I think I have a slight preference for just putting them top-level, but I certainly understand and agree with the downsides of that)

[rhshadrach]

I'm +1 on putting them in pandas.api, +0 on top-level, +0 on leaving them as-is.

[phofl]

We reverted the change of path, so this unblocks this issue from the release