enhance docstring with code examples

[wyli]

most pytorch modules come with nice examples in the docstring. for example, the docstring of torch.nn.modules.Conv1d has this block:

    Examples::
        >>> m = nn.Conv1d(16, 33, 3, stride=2)
        >>> input = torch.randn(20, 16, 50)
        >>> output = m(input)
    .. _cross-correlation:
        https://en.wikipedia.org/wiki/Cross-correlation
    .. _link:
        https://github.com/vdumoulin/conv_arithmetic/blob/master/README.md

these are also available in the autogenerated documentation site:

MONAI's modules should also include such intuitive examples.

(currently It's been done for only a few classes, e.g.:
https://github.com/Project-MONAI/MONAI/blob/master/monai/transforms/croppad/array.py#L164-L176)

Describe the solution you'd like
I understand it'll be difficult to enforce this feature for all modules. but once it's there it'll greatly improve usability. this feature request will probably require multiple PRs.

as a starting point, we could extract some examples from the existing unit tests.

[htudu]

Hi @wyli,
I would like to work on this. is it open for anyone to contribute?

[wyli]

Hi @wyli,
I would like to work on this. is it open for anyone to contribute?

yes, it is, please feel free to create PRs (there's a contributing.md in case you haven't read it)

[hjmjohnson]

@wyli I was planning to have my team work on some of this as we work through using MONAI on our projects. It is a next item after type hinting is in better shape.

[hjmjohnson]

@benjamin-gorman @crtrentz Please keep an eye on this issue, you will be asked to contribute to this effort later this summer.

[wyli]

this is a general proposal and has been implemented for many components, I'm converting it to the discussions