Add docstrings to scripts

[smoia]

Closes #1 .
Added docstrings for utils.py and viz.py.

Are we happy with the docstrings or should we expand more main() in phys2bids.py?

[rmarkello]

I'm happy to go through and review this but I have a quick question before getting started: are we trying to follow numpydoc conventions? If so, I'll comment on all the places where the docs are currently not doing that, but I didn't want to do that without checking!

[smoia]

I answer to your question with a question: what is the numpydoc convention for outputs (as in: files written to disk)?

[rmarkello]

There's nothing in particular to highlight that a function will save a file to disk (see, for example, np.savetxt). Having something at the top of the function doc-string to note that it's generating a file seems sufficient.

But I think, generally speaking, following numpydoc conventions can be really useful since they're a pretty widely-used standard and it would help Python users coming from other projects more quickly get acquainted with the codebase.

[smoia]

Ok, then: I'm going to momentarily close this issue, make the docstrings more numpyish, but maintain the "Outcome" for when we save something to the disk or print something on screen.

[eurunuela]

LGTM!