consolidate docstring style

There are a couple of different docstring formats being used in rez right now, we should decide on a convention and stick to it.

First, we need to decide what documentation generator we will use as that will dictate the available styles. I think that sphinx is the obvious choice, because it is the only actively maintained documentation generator for python out there. I've used epydoc, and it was easy to use, but it was already pretty outdated 5 years ago, so I would not bet on that horse now. Doxygen was designed for C++ and its python support is just a hack on top of that. IIRC, it could not do python introspection on live python objects like sphinx and epydoc, it could just parse python code.

So, if sphinx is the choice we have 3 styles to choose from: native, numpy, and google. here's a sphinx extension that adds supports for the latter 2: http://sphinx-doc.org/latest/ext/napoleon.html

Here they are for your simple viewing pleasure:

**sphinx**

``` python
def func(arg1, arg2):
"""Summary line.

Extended description of function.

:param arg1: Description of arg1
:type arg1: int
:param arg2: Description of arg2
:type arg2: str
:returns: Description of return value
:rtype: bool

"""
return True
```

**numpy**

``` python
def func(arg1, arg2):
"""Summary line.

Extended description of function.

Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2

Returns
-------
bool
Description of return value

"""
return True
```

**google**

``` python
def func(arg1, arg2):
"""Summary line.

Extended description of function.

Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2

Returns:
bool: Description of return value

"""
return True
```

A note on sphinx:

If you have not used sphinx before, but you have used other documentation generators like epydoc, it might be confusing at first. It is important to know that sphinx is designed in layers: the primary layer is a pure restructuredText parser, which translates an rst file into rich output like html, usually one html file per rst file. Hence, most of the sphinx documentation covers writing restructuredText documents from scratch and has nothing to say about generating API documentation from source code. That is handled by a set of extensions (namely, the autodoc extension) which generate rst documents from python modules and their docstrings, which are then converted into rich output as a second pass.

No files or tests are named. Begin by inventorying the existing Python docstring formats and evaluating the proposed Sphinx styles; the work is done when a documentation generator and one convention are decided and the project has adopted that convention consistently.

Written by the indexing model from the issue text.