numpydoc sphinx extension disabled. was: Docstring convention
**edit:** totally misguided.

Sphinx has great support for method signature metadata in docstrings,
there are python standars for ReST docstrings, and tooling to leverage
and generate the docstrings.

<del>In practice pandas uses an ad-hoc "visual" format for docstrings, which
confuses sphinx and impedes automation.

Major cleanup all over.
</del>


http://www.python.org/dev/peps/pep-0257/
http://www.python.org/dev/peps/pep-0287/

**edit:** numpydoc is in use by pandas, unbeknownst to me previously.
#2916, #3422

Bad:

```
"""
        Parameters
        ----------
        key : for use with a lock

        Returns
        -------
        res : 3.5% annualized
"""
```

Better:

```
"""
:param key:  for use with a lock
:returns: 3.5% annualized
 """
```

Much Better:

```
"""Subject

some text

a code example::

    I.am.code(is=True)

:param key: for use with a lock
:type key: str
:returns: 3.5% annualized
:rtype: float
"""
```
