Insert a section Examples in the docstring.

[JulienPeloton]

Hi,

First of all thanks for developing this Atom package, it is a great one!

I'm using the Examples section a lot in my docstrings, and I was using a modified version of your package to have it by default. And I feel like it could be useful for others.

This PR adds a section Examples to illustrate how to use the function/class, and improve the use of doctest. Here is an example using Numpy style:

def toto(a: int, b: float = 4) -> str:
    """Short summary.

    Parameters
    ----------
    a : int
        Description of parameter `a`.
    b : float
        Description of parameter `b` (the default is 4).

    Returns
    -------
    str
        Description of returned object.

    Raises
    -------
    ExceptionName
        Why the exception is raised.

    Examples
    -------
    Examples should be written in doctest format, and
    should illustrate how to use the function/class.
    >>>

    """

One remark though: The section is generated by default (set to true in config.js). Let me know if you prefer to unset it by default.

Thanks! Julien

[JulienPeloton]

Actually, I do not want to modify the test suite (it seems that you test only most required features like Parameters and Returns) - and setting the Examples section to true in config.js causes obvious troubles to it. So it I set to false by default.