Improve an render ResamplingFunction's documentation

[llucax]

What's needed?

The resampling function documentation is not visible, as it is not included in the generated docs. It is also incomplete, as it doesn't mention the some details of what resampling function should expect as input samples.

frequenz-sdk-python/src/frequenz/sdk/timeseries/_resampling.py

Lines 75 to 100 in 6d106d1

	ResamplingFunction = Callable[
	[Sequence[Sample[Quantity]], "ResamplerConfig", "SourceProperties"], float
	]
	"""Resampling function type.
	A resampling function produces a new sample based on a list of pre-existing
	samples. It can do "upsampling" when the data rate of the `input_samples`
	period is smaller than the `resampling_period`, or "downsampling" if it is
	bigger.
	In general a resampling window is the same as the `resampling_period`, and
	this function might receive input samples from multiple windows in the past to
	enable extrapolation, but no samples from the future (so the timestamp of the
	new sample that is going to be produced will always be bigger than the biggest
	timestamp in the input data).
	Args:
	input_samples (Sequence[Sample]): The sequence of pre-existing samples.
	resampler_config (ResamplerConfig): The configuration of the resampling
	calling this function.
	source_properties (SourceProperties): The properties of the source being
	resampled.
	Returns:
	new_sample (float): The value of new sample produced after the resampling.
	"""

Proposed solution

Expose the alias to the docs and clarify:

• It probably needs to use the term "relevant samples" (as the samples in the time windows as defined by resampling_period and max_data_age_in_periods) when saying which samples are passed. ¹
• It needs to clarify that sample's values can only be numbers or if it can include nan or None (what about ìnf`?)
• It needs to clarify that if there are no relevant samples, then the resampling function is not called at all (so resampling functions have guaranteed that samples can't be an empty collection).

Footnotes

1. The resampling helper class mentions:

   All collected samples that are newer than max(resampling_period, input_period). max_data_age_in_periodsare considered *relevant* and are passed to the providedresampling_functionwhen calling theresample()` method.

   ↩