Make docs consistent

[ericmjl]

Our docstrings should have some standards. I would like to propose the following standards:

def function(*args, **kwargs):
    """One-liner description of what the function does.

    Further elaborations as necessary. 

    Multiple lines for further elaborations is perfectly fine.

    :param arg1: Description of arg1 and what it controls.
    :param arg2: etc.
    :param kwarg1: etc.
    :param kwarg2: etc.
    :returns: Description of returns
    """

That should be all that's included.

With MkDocs, search will be really good. There can be a notebook series where we do "how to use function X". This is a very good Google Summer of Code project, btw.

[loganthomas]

I agree 💯

A recent review of timeseries.flag_jumps() is too verbose and the detailed examples should be in a Jupyter Noteboook.

    Detailed chaining examples:

        # Applies specified criteria across all columns of the dataframe
        # Appends a flag column for each column in the dataframe
        df = (
            pd.DataFrame(...)
            .flag_jumps(
                scale="absolute",
                direction="any",
                threshold=2
            )
        )

        # Applies specific criteria to certain dataframe columns
        # Applies default criteria to columns not specifically listed
        # Appends a flag column for each column in the dataframe
        df = (
            pd.DataFrame(...)
            .flag_jumps(
                scale=dict(col1="absolute", col2="percentage"),
                direction=dict(col1="increasing", col2="any"),
                threshold=dict(col1=1, col2=0.5),
            )
        )

        # Applies specific criteria to certain dataframe columns
        # Applies default criteria to columns not specifically listed
        # Appends a flag column for each column in the dataframe
        df = (
            pd.DataFrame(...)
            .flag_jumps(
                scale=dict(col1="absolute"),
                direction=dict(col2="increasing"),
            )
        )

        # Applies specific criteria to certain dataframe columns
        # Applies default criteria to columns not specifically listed
        # Appends a flag column for only those columns found in
        #   specified criteria
        df = (
            pd.DataFrame(...)
            .flag_jumps(
                scale=dict(col1="absolute"),
                threshold=dict(col2=1),
                strict=True,
            )
        )

This should certainly be in an example file somewhere rather than a docstring IMO. I wrote this so I am completely at fault 😅