DOC: documentation rendering issue for functions using typing overloads

[shaido987]

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.concat.html

Documentation problem

This is how the method header looks for concat:

pandas.concat(objs: Union[Iterable[‘DataFrame’], Mapping[Label, ‘DataFrame’]], axis='0', join: str = "'outer'", 
ignore_index: bool = 'False', keys='None', levels='None', names='None', verify_integrity: bool = 'False', 
sort: bool = 'False', copy: bool = 'True') → ’DataFrame’
pandas.concat(objs: Union[Iterable[FrameOrSeries], Mapping[Label, FrameOrSeries]], axis='0', join: str = "'outer'", 
ignore_index: bool = 'False', keys='None', levels='None', names='None', verify_integrity: bool = 'False', 
sort: bool = 'False', copy: bool = 'True') → FrameOrSeriesUnion

For comparison, this is merge:

pandas.merge(left, right, how='inner', on=None, left_on=None, right_on=None, left_index=False, 
right_index=False, sort=False, suffixes='_x', '_y', copy=True, indicator=False, validate=None)

As can be seen above, concat keeps the type information and there are two entries (likely due to the different output types).

I'm not sure why this occurs, but there are several overloaded methods in the code which could be related:

pandas/pandas/core/reshape/concat.py

Lines 40 to 83 in 54fa3da

	@overload
	def concat(
	objs: Union[Iterable["DataFrame"], Mapping[Label, "DataFrame"]],
	axis=0,
	join: str = "outer",
	ignore_index: bool = False,
	keys=None,
	levels=None,
	names=None,
	verify_integrity: bool = False,
	sort: bool = False,
	copy: bool = True,
	) -> "DataFrame":
	...
	@overload
	def concat(
	objs: Union[Iterable["NDFrame"], Mapping[Label, "NDFrame"]],
	axis=0,
	join: str = "outer",
	ignore_index: bool = False,
	keys=None,
	levels=None,
	names=None,
	verify_integrity: bool = False,
	sort: bool = False,
	copy: bool = True,
	) -> FrameOrSeriesUnion:
	...
	def concat(
	objs: Union[Iterable["NDFrame"], Mapping[Label, "NDFrame"]],
	axis=0,
	join="outer",
	ignore_index: bool = False,
	keys=None,
	levels=None,
	names=None,
	verify_integrity: bool = False,
	sort: bool = False,
	copy: bool = True,
	) -> FrameOrSeriesUnion:

[jorisvandenbossche]

@shaido987 thanks a lot for the report. Those overloads should indeed not be shown. This seems to be a bug in sphinx, see sphinx-doc/sphinx#7785

In general, also see #33025 for showing type annotations in the docs or not.

[simonjayhawkins]

Thanks @shaido987

we were aware of this, see #36475 (comment), but that is obviously not so visible as a dedicated issue.

But at the same time, i'm also happy to close this as it is a sphinx issue.

[jorisvandenbossche]

The sphinx bug has been fixed in sphinx 3.3, so the latest docs also show this correctly now, see eg https://pandas.pydata.org/pandas-docs/version/1.2.0/reference/api/pandas.concat.html vs https://pandas.pydata.org/pandas-docs/version/1.1.0/reference/api/pandas.concat.html

So I think we can close it here.