Python Coding Conventions: Clarify docstring conventions, especially for array shapes

[jchodera]

We should further clarify docstring conventions, especially for optional arguments and array shapes.

Type hints will also help with this.

[jchodera]

sphinx-autodoc-typehints could auto-generate from type hints---do we want to use this?