Rewrite docs using Numpy docstrings

[mileslucas]

Is there any opposition to converting to use NumPy style docstrings? In my opinion they are simpler to read when seeing the code, and sphinx has built-in support for it. Here is an example of the ReST vs numpy docstrings-

ReST docstring

def download_PHOENIX_models(parameters, base=config.grid["raw_path"]):
    """
    Download the PHOENIX grid models from the Goettingen servers. This will skip over any ill-defined files or any
    files that already exist on disk in the given folder.
    :param parameters: The parameters to download. Should be a list of parameters where parameters can either be
        [Teff, logg, Z] or [Teff, logg, Z, Alpha]. All values should be floats or integers and not string.
    :type parameters: iterable of iterables of length 3 or length 4
    :param base: The base directory to save the files in. Default is specified by the ``grid.raw_path`` in the
        ``config.yaml`` file
    :type base: str or path-like
    .. warning:: This will create any directories if they do not exist
    .. warning:: Please use this responsibly to avoid over-saturating the connection to the Gottinghen servers.
    Example usage
    .. code-block:: python
        from itertools import product
        from Starfish.grid_tools import download_PHOENIX_models
        T = [5000, 5100, 5200]
        logg = [4.0, 4.5, 5.0]
        Z = [0]
        Alpha = [0, -0.2]
        params = product(T, logg, Z, Alpha)
        download_PHOENIX_models(params, base='models')
    """

Numpy docstring

def download_PHOENIX_models(parameters, base=config.grid["raw_path"]):
    """
    Download the PHOENIX grid models from the Goettingen servers.
    This will skip over any ill-defined files or any files that already exist on disk in the given folder.
    Parameters
    ----------
    parameters : array_like of tuples of length 3 or 4
        The parameters to download. Should be a list of parameters where parameters can either be
        [Teff, logg, Z] or [Teff, logg, Z, Alpha]. All values should be floats or integers and not string.
    base : str or path-like, optional
        The base directory to save the files in. Default is specified by the ``grid.raw_path`` in the
        ``config.yaml`` file
    Warning
    -------
        This will create any directories if they do not exist
    Warning
    -------
        Please use this responsibly to avoid over-saturating the connection to the Gottinghen servers.
    Example
    -------
    >>> from itertools import product
    >>> from Starfish.grid_tools import download_PHOENIX_models
    >>> T = [5000, 5100, 5200]
    >>> logg = [4.0, 4.5, 5.0]
    >>> Z = [0]
    without using Alpha parameter
    >>> params = product(T, logg, Z)
    >>> download_PHOENIX_models(params, base='models')
    with using Alpha parameter
    >>> Alpha = [0, -0.2]
    >>> params = product(T, logg, Z, Alpha)
    >>> download_PHOENIX_models(params, base='models')
    """

(I'm aware they are not equivalent examples but the general point stands).

This is not a high-priority issue but something to consider for code clarity and documentation.

If we are okay with this, and someone wants to do the conversion, feel free to pull docs/numpy-docstrings and work on it. I won't have time for this while I'm working on the new modelling method.

[iancze]

I think moving to numpy docstrings is a great idea! I'm not sure why we didn't do this in the first place (probably I didn't know any better).

[jason-neal]

I'll give this a go, I've got 25+ hours of flying to do today.

[mileslucas]

@jason-neal

I’ve inadvertently done most of this on my develop branch, so I wouldn’t put work into it especially on master!