Adopt docstring convention

[ns-rse]

The Scientific Python Documentation Tutorial recommends using numpydoc formatted docstrings in Python as they work well with Sphinx's autodoc and autosummary extensions.

I appreciate not all Python projects will be scientifically aligned but many would be.

This would encourage the use of Type Hints which code bases benefit from having as there are linters which can check type hints are consistent and correct which in turn reduces the amount of errors that can arise when running code (using Type Hints in examples could easily be a separate issue though).

There is also a convention for adding examples sections to docstrings and these can even form the basis of tests for a package via the standard libraries doctest (and of course pytest supports doctest.

Using Type Hints and adding Examples could easily be their own issues so listing below to facilitate creation of these if it is desirable to do so.

• Add Type Hints to docstrings for Python examples.
• Add Examples to docstrings for Python examples.