Request: Use Sphinx docstring to infer type of function arguments about jedi HOT 12 CLOSED

Other popular docstring syntax to document function parameter is numpydocs https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#id6

from jedi.

I've had this idea once before, but at the moment I don't have the time to add this, could be a good addition.

from jedi.

Are there any other (popular) ways to declare types for python params?

from jedi.

I found something: http://www.python.org/dev/peps/pep-0257/ (but I really would like to know about other types).

from jedi.

There are also "googley" docstrings:

"""This function does something.

    Args:
       name (str):  The name to use.

    Kwargs:
       state (bool): Current state to be in.

    Returns:
       int.  The return code::

          0 -- Success!
          1 -- No good.
          2 -- Try again.

    Raises:
       AttributeError, KeyError
"""

from jedi.

No, I don't know other styles (including that google style!). I think Sphinx is a good first step, as I assume it is the most famous and used style and you can use docutils instead of writing your own.

from jedi.

In matplotlib, ReST table is used for documenting keyword arguments. But I guess supporting this style won't help people other than matplotlib devs.

          ================   =========================================
          Keyword            Description
          ================   =========================================
          *adjustable*       [ 'box' | 'datalim' | 'box-forced']
          *alpha*            float: the alpha transparency (can be None)
          *anchor*           [ 'C', 'SW', 'S', 'SE', 'E', 'NE', 'N',
                               'NW', 'W' ]
          *aspect*           [ 'auto' | 'equal' | aspect_ratio ]
          *autoscale_on*     [ *True* | *False* ] whether or not to
                             autoscale the *viewlim*
          ...

https://github.com/matplotlib/matplotlib/blob/master/lib/matplotlib/axes.py#L392-433

from jedi.

I added sphinx docstrings and "googley" docstrings. I ignored the matplotlib ones because they are not typical for Python and also ignored numpy docstrings (for now) because they might be misinterpreted.

from jedi.

This is really cool! Thank you very much.

from jedi.

It's really only the basics, I have to improve things like list of str...

from jedi.

I didn't found any definition of googley docstrings. The only tink I found is http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments which does not provide any format for param types or return types.

I'd like to remove google docstrings support to keep existing code clean and simple. Unless someone provide docstrings api(format) atleast.

from jedi.

You're probably right. The reason why I included it in the first place was this: http://packages.python.org/an_example_pypi_project/sphinx.html

But that's just an example. No specification. So feel free to remove it.

from jedi.