diff --git a/docs/docs/features.rst b/docs/docs/features.rst index 3f95fd5e..080d0395 100644 --- a/docs/docs/features.rst +++ b/docs/docs/features.rst @@ -109,130 +109,6 @@ This is intentional: Most people trust the code bases they have imported, because at that point a malicious code base would have had code execution already. -Recipes -------- - -Here are some tips on how to use |jedi| efficiently. - - -.. _type-hinting: - -Type Hinting -~~~~~~~~~~~~ - -If |jedi| cannot detect the type of a function argument correctly (due to the -dynamic nature of Python), you can help it by hinting the type using -one of the docstring/annotation styles below. **Only gradual typing will -always work**, all the docstring solutions are glorified hacks and more -complicated cases will probably not work. - -Official Gradual Typing (Recommended) -+++++++++++++++++++++++++++++++++++++ - -You can read a lot about Python's gradual typing system in the corresponding -PEPs like: - -- `PEP 484 `_ as an introduction -- `PEP 526 `_ for variable annotations -- `PEP 589 `_ for ``TypeDict`` -- There are probably more :) - -Below you can find a few examples how you can use this feature. - -Function annotations:: - - def myfunction(node: ProgramNode, foo: str) -> None: - """Do something with a ``node``. - - """ - node.| # complete here - - -Assignment, for-loop and with-statement type hints:: - - import typing - x: int = foo() - y: typing.Optional[int] = 3 - - key: str - value: Employee - for key, value in foo.items(): - pass - - f: Union[int, float] - with foo() as f: - print(f + 3) - -PEP-0484 should be supported in its entirety. Feel free to open issues if that -is not the case. You can also use stub files. - - -Sphinx style -++++++++++++ - -http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists - -:: - - def myfunction(node, foo): - """ - Do something with a ``node``. - - :type node: ProgramNode - :param str foo: foo parameter description - """ - node.| # complete here - -Epydoc -++++++ - -http://epydoc.sourceforge.net/manual-fields.html - -:: - - def myfunction(node): - """ - Do something with a ``node``. - - @type node: ProgramNode - """ - node.| # complete here - -Numpydoc -++++++++ - -https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt - -In order to support the numpydoc format, you need to install the `numpydoc -`__ package. - -:: - - def foo(var1, var2, long_var_name='hi'): - r""" - A one-line summary that does not use variable names or the - function name. - - ... - - Parameters - ---------- - var1 : array_like - Array_like means all those objects -- lists, nested lists, - etc. -- that can be converted to an array. We can also - refer to variables like `var1`. - var2 : int - The type above can either refer to an actual Python type - (e.g. ``int``), or describe the type of the variable in more - detail, e.g. ``(N,) ndarray`` or ``array_like``. - long_variable_name : {'hi', 'ho'}, optional - Choices in brackets, default first when optional. - - ... - - """ - var2.| # complete here - A little bit of history ----------------------- diff --git a/docs/docs/usage.rst b/docs/docs/usage.rst index d9f3f7f9..0ce532ca 100644 --- a/docs/docs/usage.rst +++ b/docs/docs/usage.rst @@ -1,11 +1,13 @@ .. include:: ../global.rst -End User Usage -============== +Using Jedi +========== -|jedi| is can be used in a variety of plugins and software. It is also possible +|jedi| is can be used with a variety of plugins and software. It is also possible to use |jedi| in the :ref:`Python shell or with IPython `. +Below you can also find a list of :ref:`recipes for type hinting `. + .. _editor-plugins: @@ -105,6 +107,132 @@ Using a Custom ``$HOME/.pythonrc.py`` .. autofunction:: jedi.utils.setup_readline +.. _recipes: + +Recipes +------- + +Here are some tips on how to use |jedi| efficiently. + + +.. _type-hinting: + +Type Hinting +~~~~~~~~~~~~ + +If |jedi| cannot detect the type of a function argument correctly (due to the +dynamic nature of Python), you can help it by hinting the type using +one of the docstring/annotation styles below. **Only gradual typing will +always work**, all the docstring solutions are glorified hacks and more +complicated cases will probably not work. + +Official Gradual Typing (Recommended) ++++++++++++++++++++++++++++++++++++++ + +You can read a lot about Python's gradual typing system in the corresponding +PEPs like: + +- `PEP 484 `_ as an introduction +- `PEP 526 `_ for variable annotations +- `PEP 589 `_ for ``TypeDict`` +- There are probably more :) + +Below you can find a few examples how you can use this feature. + +Function annotations:: + + def myfunction(node: ProgramNode, foo: str) -> None: + """Do something with a ``node``. + + """ + node.| # complete here + + +Assignment, for-loop and with-statement type hints:: + + import typing + x: int = foo() + y: typing.Optional[int] = 3 + + key: str + value: Employee + for key, value in foo.items(): + pass + + f: Union[int, float] + with foo() as f: + print(f + 3) + +PEP-0484 should be supported in its entirety. Feel free to open issues if that +is not the case. You can also use stub files. + + +Sphinx style +++++++++++++ + +http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists + +:: + + def myfunction(node, foo): + """ + Do something with a ``node``. + + :type node: ProgramNode + :param str foo: foo parameter description + """ + node.| # complete here + +Epydoc +++++++ + +http://epydoc.sourceforge.net/manual-fields.html + +:: + + def myfunction(node): + """ + Do something with a ``node``. + + @type node: ProgramNode + """ + node.| # complete here + +Numpydoc +++++++++ + +https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt + +In order to support the numpydoc format, you need to install the `numpydoc +`__ package. + +:: + + def foo(var1, var2, long_var_name='hi'): + r""" + A one-line summary that does not use variable names or the + function name. + + ... + + Parameters + ---------- + var1 : array_like + Array_like means all those objects -- lists, nested lists, + etc. -- that can be converted to an array. We can also + refer to variables like `var1`. + var2 : int + The type above can either refer to an actual Python type + (e.g. ``int``), or describe the type of the variable in more + detail, e.g. ``(N,) ndarray`` or ``array_like``. + long_variable_name : {'hi', 'ho'}, optional + Choices in brackets, default first when optional. + + ... + + """ + var2.| # complete here + .. _jedi-vim: https://github.com/davidhalter/jedi-vim .. _youcompleteme: https://valloric.github.io/YouCompleteMe/ .. _deoplete-jedi: https://github.com/zchee/deoplete-jedi