Move recipes to Jedi Usage

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 <https://www.python.org/dev/peps/pep-0484/>`_ as an introduction
-- `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ for variable annotations
-- `PEP 589 <https://www.python.org/dev/peps/pep-0589/>`_ 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
-<https://pypi.python.org/pypi/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
 -----------------------
 

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 <repl-completion>`.
 
+Below you can also find a list of :ref:`recipes for type hinting <recipes>`.
+
 
 .. _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 <https://www.python.org/dev/peps/pep-0484/>`_ as an introduction
+- `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ for variable annotations
+- `PEP 589 <https://www.python.org/dev/peps/pep-0589/>`_ 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
+<https://pypi.python.org/pypi/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