Standardize docstrings

[choldgraf]

trafficstars

we should probably standardize our docstrings

I have been using numpydoc style, which looks like this:

Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified)

but I noticed @chrisjsewell has been using a different style (not sure exactly which, but it looks like the following)

:param text: the file text
:param code_directive: the name of the directive to search for containing code cells
:param raw_directive: the name of the directive to search for containing raw cells
:param add_source_map: add a `source_map` key to the notebook metadata,
 is a list of the starting source line number for each cell.
:raises MystMetadataParsingError if the metadata block is not valid JSON/YAML

We should just pick one and use that...

[chrisjsewell]

See the last para in https://myst-nb.readthedocs.io/en/latest/develop/contributing.html#code-style and https://myst-parser.readthedocs.io/en/latest/develop/contributing.html#code-style, and https://jupyter-cache.readthedocs.io/en/latest/develop/contributing.html#code-style 😄

I used to use the numpydoc format, but with the introduction of type annotations, having the type in the doctring is kind of obsolete, i.e.

def func(x, y):
    """
    Parameters
    ----------
    x : str
        Description of parameter `x`.
    y:
        Description of parameter `y` (with type not specified)

    Returns
    ---------
    str: description
    """
    pass

is more concise (and better for auto-completion) using the sphinx format + annotations:

from typing import Any

def func(x: str, y: Any) -> str:
    """
    :param x: Description of parameter `x`.
    :param y: Description of parameter `y`
    :returns: description
    """
    pass