numpydoc sphinx extension disabled. was: Docstring convention

[ghost]

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.

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

Major cleanup all over.

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
"""

[jseabold]

This is the numpy docstring standard parsed with sphinxext/numpydoc.py. I'd be strongly against doing away with it since it's the de facto standard across many packages and what many people have come to expect. It's much easier to look at vs. the examples you've posted assuming this is what I'd see at the interpreter. What do you mean it confuses sphinx and impedes automation?

[ghost]

Thanks, I wasn't in on that.

I think I unceremoniously kicked out numpydoc due to this:
https://github.com/pydata/pandas-website/issues/20

Could see no diff at the time, probably explains why sphinx is yelling a lot.

The format seems to be harder to parse, that's what I meant by "impedes automation",
because it looks like free text.

[jseabold]

Oh ok. It can be a real pain to get to zero warning docs builds the first time, if no one has been keeping up with it, but it's certainly possible. In my experience there's no such thing as a false positive warning. They all indicate some kind of formatting error which will show up in the built documentation.

[ghost]

Pretty sure I screwed up the 0.11.0 documentation for all distros until 0.12 comes out. nice.
cc/f***up @changhiskhan , @wesm

e6aaca5: DOC: bring back numpydoc

[jseabold]

Luckily in my experience no one ever reads the documentation ;)

[ghost]

well, maybe if you didn't use scary words like exogenous everywhere you'd
gain more traction :)

[jseabold]

Feel free to add your voice to this "fun" discussion

statsmodels/statsmodels#395