Add "Reference Examples"

[seanlaw]

In our API documentation, some parameters are described but it may not seem obvious how to use them. Thus, it would be beneficial to add additional "reference examples". For instance, throughout our API, we have the parameter T_A_subseq_isconstant, which has the rather technical description of:

A boolean array that indicates whether a subsequence in T_A is constant (True). Alternatively, a custom, user-defined function that returns a boolean array that indicates whether a subsequence in T_A is constant (True). The function must only take two arguments, a, a 1-D array, and w, the window size, while additional arguments may be specified by currying the user-defined function using functools.partial. Any subsequence with at least one np.nan/np.inf will automatically have its corresponding value set to False in this boolean array.

It would be nice to provide a separate example of what a "user-defined function" would look like and to stick it into a reference section outside of the API documentation but with a cross-reference inserted.

According to the diataxis:

Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.

Reference material contains propositional or theoretical knowledge that a user looks to in their work.

The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way. Whereas the content of tutorials and how-to guides are led by needs of the user, reference material is led by the product it describes.

So, the reference example should be succinct and not verbose (like the tutorials). I'd prefer a short technical description (if necessary) and then a code example:

import numpy as np
import stumpy

def custom_isconstant_func(a, w):
    isconstant_array = numpy.full(a - w + 1, False, dtype=bool)
    for i in range(a - w + 1):
        if np.min(a[i : i + w]) == np.max(a[i : i + w]):
            isconstant_array[i] = True
    ...
    return isconstant_array

stumpy.stump(T, m, T_A_subseq_isconstant=custom_isconstant_func)