Add minimum examples in header of the functions

[ACHMartin]

to add a self sufficient example on how to use the function

[ACHMartin]

@DavidMcCann-NOC, could you have a first look on the format to be used. Either you can provide a first example or point me to the relevant documentation.

[DavidMcCann-NOC]

Here is the example documentation for the NumPy docstring style. I think the relevant header for us is 'Example', we can use Notes for functions like the gmfs that have DOIs to the relevant literature etc.

"""Example NumPy style docstrings.

This module demonstrates documentation as specified by the NumPy Documentation HOWTO_. Docstrings may extend over multiple lines. Sections are created with a section header followed by an underline of equal length.

Example

Examples can be given using either the Example or Examples sections. Sections support any reStructuredText formatting, including literal blocks::

$ python example_numpy.py

Section breaks are created with two blank lines. Section breaks are also implicitly created anytime a new section starts. Section bodies may be indented:

Notes

This is an example of an indented section. It's like any other section,
but the body is indented to help it stand out from surrounding text.

If a section is indented, then a section break is created by resuming unindented text.

[DavidMcCann-NOC]

Here is the documentation: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html