From e6ef96412e7a2cfa1c3b8796c8ed852c909fc527 Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Fri, 1 Mar 2013 15:42:31 +0100 Subject: [PATCH 1/9] Add vimdoc documentation For now, this is just the README.rst file with appropriate sections. The content of the file itself is completely unchanged. Section name suggestions are taken from Steve Losh's Learn Vimscript the Hard Way [1]. Formatting suggestions are taken from Vim's own documentation on writing help files (:help help-writing). The spiffy header was created using the figlet program [2] and the starwars.flf font found in the figlet fonts database [3]. [1] http://learnvimscriptthehardway.stevelosh.com/chapters/54.html [2] http://www.figlet.org [3] http://www.figlet.org/fonts/starwars.flf --- doc/jedi-vim.txt | 167 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 doc/jedi-vim.txt diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt new file mode 100644 index 0000000..aa22352 --- /dev/null +++ b/doc/jedi-vim.txt @@ -0,0 +1,167 @@ +*jedi-vim.txt* - For Vim version 7.3 - Last change: 2013/3/1 + __ _______ _______ __ ____ ____ __ .___ ___.~ + | | | ____|| \ | | \ \ / / | | | \/ |~ + | | | |__ | .--. || | _____\ \/ / | | | \ / |~ +.--. | | | __| | | | || | |______\ / | | | |\/| |~ +| `--' | | |____ | '--' || | \ / | | | | | |~ + \______/ |_______||_______/ |__| \__/ |__| |__| |__|~ + + jedi-vim - awesome Python autocompletion with VIM + **now in beta testing phase** + +============================================================================== +CONTENTS *jedi-vim-contents* + + 1. Introduction |jedi-vim-introduction| + 2. Installation |jedi-vim-installation| + 3. Support |jedi-vim-support| + 4. Usage |jedi-vim-usage| + 5. Mappings |jedi-vim-mappings| + 6. Configuration |jedi-vim-configuration| + 7. Contributing |jedi-vim-contributing| + + +============================================================================== +1. Introduction *jedi-vim-introduction* + +jedi-vim is a is a VIM binding to the awesome autocompletion library *Jedi*. + +Here are some pictures: + +.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_complete.png + +Completion for almost anything (Ctrl+Space). + +.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_function.png + +Display of function/class bodies, docstrings. + +.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_pydoc.png + +Pydoc support (with highlighting, Shift+k). + +There is also support for goto and renaming. + + + +============================================================================== +2. Installation *jedi-vim-installation* + +Get the latest from `github `_. + +You can get the Jedi library `here `_. + +You might want to use `pathogen `_ to +install jedi in Vim. Also you need a VIM version that was compiled with +``+python``, which is typical for most distributions on Linux. + +The first thing you need after that is an up-to-date version of Jedi. You can +either get it via ``pip install jedi`` or with ``git submodule update --init`` +in your jedi-vim repository. + +On Arch Linux, you can also install jedi-vim from AUR: `vim-jedi +`__. + +============================================================================== +3. Support *jedi-vim-support* + +The Jedi library supports most of Python's core features. From decorators to +generators, there is broad support. + +============================================================================== +4. Usage *jedi-vim-usage* + +The autocompletion can be used with , if you want it to work with + you can use `supertab `_. + +============================================================================== +5. Mappings *jedi-vim-mappings* + +============================================================================== +6. Configuration *jedi-vim-configuration* + +Jedi is by default automatically initialized. If you don't want that I suggest +you disable the auto-initialization in your ``.vimrc``: + +.. code-block:: vim + + let g:jedi#auto_initialization = 0 + +There are also some VIM options (like ``completeopt``) which are automatically +initialized, if you don't want that: + +.. code-block:: vim + + let g:jedi#auto_vim_configuration = 0 + +The goto is by default on . If you want to change that: + +.. code-block:: vim + + let g:jedi#goto_command = "g" + +``get_definition`` is by default on . If you want to change that: + +.. code-block:: vim + + let g:jedi#get_definition_command = "d" + +Showing the pydoc is by default on ``K`` If you want to change that: + +.. code-block:: vim + + let g:jedi#pydoc = "K" + +If you are a person who likes to use VIM-buffers not tabs, you might want to +put that in your ``.vimrc``: + +.. code-block:: vim + + let g:jedi#use_tabs_not_buffers = 0 + +Jedi automatically starts the completion, if you type a dot, e.g. ``str.``, if +you don't want this: + +.. code-block:: vim + + let g:jedi#popup_on_dot = 0 + +Jedi selects the first line of the completion menu: for a better typing-flow and +usually saves one keypress. + +.. code-block:: vim + + let g:jedi#popup_select_first = 0 + +There's some support for refactoring: + +.. code-block:: vim + + let g:jedi#rename_command = "r" + +And you can list all names that are related (have the same origin): + +.. code-block:: vim + + let g:jedi#related_names_command = "n" + +If you want to change the default autocompletion command: + +.. code-block:: vim + + let g:jedi#autocompletion_command = "" + +By default you get a window that displays the function definition you're +currently in. If you don't want that: + +.. code-block:: vim + + let g:jedi#show_function_definition = "0" + +============================================================================== +7. Contributing *jedi-vim-contributing* + +If you have any comments or feature requests, please tell me! I really want +to know, what you think about Jedi and jedi-vim. + + vim: textwidth=78 tabstop=8 filetype=help:norightleft: From 4bc8a4445326fd98733425f78c28cd7fce18dcf4 Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Fri, 1 Mar 2013 16:11:19 +0100 Subject: [PATCH 2/9] Cosmetic and formatting fixes - Remove images in introduction - Replace all occurences of VIM with Vim - Use Vim code blocks - Surround all keybindings with <> --- doc/jedi-vim.txt | 108 +++++++++++++++++------------------------------ 1 file changed, 39 insertions(+), 69 deletions(-) diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index aa22352..5dac926 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -6,7 +6,7 @@ | `--' | | |____ | '--' || | \ / | | | | | |~ \______/ |_______||_______/ |__| \__/ |__| |__| |__|~ - jedi-vim - awesome Python autocompletion with VIM + jedi-vim - awesome Python autocompletion with Vim **now in beta testing phase** ============================================================================== @@ -24,43 +24,37 @@ CONTENTS *jedi-vim-contents* ============================================================================== 1. Introduction *jedi-vim-introduction* -jedi-vim is a is a VIM binding to the awesome autocompletion library *Jedi*. - -Here are some pictures: - -.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_complete.png - -Completion for almost anything (Ctrl+Space). - -.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_function.png - -Display of function/class bodies, docstrings. - -.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_pydoc.png - -Pydoc support (with highlighting, Shift+k). - -There is also support for goto and renaming. - +jedi-vim is a is a Vim binding to the awesome autocompletion library `Jedi`. +- Completion for almost anything. +- Display of function/class bodies, docstrings. +- Pydoc support with highlighting. +- Support for goto and renaming. ============================================================================== 2. Installation *jedi-vim-installation* -Get the latest from `github `_. +Get the latest from http://github.com/davidhalter/jedi-vim. -You can get the Jedi library `here `_. +You can get the Jedi library at http://github.com/davidhalter/jedi. -You might want to use `pathogen `_ to -install jedi in Vim. Also you need a VIM version that was compiled with -``+python``, which is typical for most distributions on Linux. +You might want to use Pathogen http://github.com/tpope/vim-pathogen to +install Jedi in Vim. Also you need Vim compiled with +python, which is +typical for most distributions on Linux. The first thing you need after that is an up-to-date version of Jedi. You can -either get it via ``pip install jedi`` or with ``git submodule update --init`` +either get it via > + + pip install jedi + +or with > + + git submodule update --init + in your jedi-vim repository. -On Arch Linux, you can also install jedi-vim from AUR: `vim-jedi -`__. +On Arch Linux, you can also install jedi-vim from AUR, with the `vim-jedi` +package. ============================================================================== 3. Support *jedi-vim-support* @@ -71,8 +65,8 @@ generators, there is broad support. ============================================================================== 4. Usage *jedi-vim-usage* -The autocompletion can be used with , if you want it to work with - you can use `supertab `_. +The autocompletion can be used with , if you want it to work with + you can use the Supertab plugin. ============================================================================== 5. Mappings *jedi-vim-mappings* @@ -81,80 +75,56 @@ The autocompletion can be used with , if you want it to work with 6. Configuration *jedi-vim-configuration* Jedi is by default automatically initialized. If you don't want that I suggest -you disable the auto-initialization in your ``.vimrc``: - -.. code-block:: vim +you disable the auto-initialization in your .vimrc: > let g:jedi#auto_initialization = 0 -There are also some VIM options (like ``completeopt``) which are automatically -initialized, if you don't want that: - -.. code-block:: vim +There are also some Vim options (like completeopt) which are automatically +initialized, if you don't want that: > let g:jedi#auto_vim_configuration = 0 -The goto is by default on . If you want to change that: - -.. code-block:: vim +The goto is by default on . If you want to change that: > let g:jedi#goto_command = "g" -``get_definition`` is by default on . If you want to change that: - -.. code-block:: vim +get_definition is by default on . If you want to change that: > let g:jedi#get_definition_command = "d" -Showing the pydoc is by default on ``K`` If you want to change that: - -.. code-block:: vim +Showing the pydoc is by default on . If you want to change that: > let g:jedi#pydoc = "K" -If you are a person who likes to use VIM-buffers not tabs, you might want to -put that in your ``.vimrc``: - -.. code-block:: vim +If you are a person who likes to use Vim buffers not tabs, you might want to +put that in your .vimrc: > let g:jedi#use_tabs_not_buffers = 0 -Jedi automatically starts the completion, if you type a dot, e.g. ``str.``, if -you don't want this: - -.. code-block:: vim +Jedi automatically starts the completion if you type a dot, e.g. "str.", if +you don't want this: > let g:jedi#popup_on_dot = 0 Jedi selects the first line of the completion menu: for a better typing-flow and -usually saves one keypress. - -.. code-block:: vim +usually saves one keypress. > let g:jedi#popup_select_first = 0 -There's some support for refactoring: - -.. code-block:: vim +There's some support for refactoring: > let g:jedi#rename_command = "r" -And you can list all names that are related (have the same origin): - -.. code-block:: vim +And you can list all names that are related (have the same origin): > let g:jedi#related_names_command = "n" -If you want to change the default autocompletion command: +If you want to change the default autocompletion command: > -.. code-block:: vim - - let g:jedi#autocompletion_command = "" + let g:jedi#autocompletion_command = "" By default you get a window that displays the function definition you're -currently in. If you don't want that: - -.. code-block:: vim +currently in. If you don't want that: > let g:jedi#show_function_definition = "0" From 84a982ee264c2fa1d01d2493c26a371e08b83690 Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Fri, 1 Mar 2013 19:20:25 +0100 Subject: [PATCH 3/9] Document keybindings and options All keybindings and options have at least a short description added to them. With this commit the general structure of a Vim help file is in place. --- doc/jedi-vim.txt | 216 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 171 insertions(+), 45 deletions(-) diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index 5dac926..a1fcbdd 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -10,19 +10,33 @@ **now in beta testing phase** ============================================================================== -CONTENTS *jedi-vim-contents* +Contents *jedi-vim-contents* - 1. Introduction |jedi-vim-introduction| - 2. Installation |jedi-vim-installation| - 3. Support |jedi-vim-support| - 4. Usage |jedi-vim-usage| - 5. Mappings |jedi-vim-mappings| - 6. Configuration |jedi-vim-configuration| - 7. Contributing |jedi-vim-contributing| +1. Introduction |jedi-vim-introduction| +2. Installation |jedi-vim-installation| +3. Support |jedi-vim-support| +4. Usage |jedi-vim-usage| +5. Mappings |jedi-vim-mappings| + 5.1. Start completion |g:jedi#autocompletion_command| + 5.2. Go to definition |g:jedi#goto_command| + 5.3. Get original definition |g:jedi#get_definition_command| + 5.4. Show documentation |g:jedi#pydoc_command| + 5.5. Rename variables |g:jedi#rename_command| + 5.6. Show related names |g:jedi#related_names_command| +6. Configuration |jedi-vim-configuration| + 6.1. auto_initialization |g:jedi#auto_initialization| + 6.2. auto_vim_configuration |g:jedi#auto_vim_configuration| + 6.3. popup_on_dot |g:jedi#popup_on_dot| + 6.4. popup_select_first |g:jedi#popup_select_first| + 6.5. auto_close_doc |g:jedi#auto_close_doc| + 6.6. show_function_definition |g:jedi#show_function_def| + 6.7. use_tabs_not_buffers |g:jedi#use_tabs_not_buffers| + 6.8. squelch_py_warning |g:jedi#squelch_py_warning| +7. Contributing |jedi-vim-contributing| ============================================================================== -1. Introduction *jedi-vim-introduction* +1. Introduction *jedi-vim-introduction* jedi-vim is a is a Vim binding to the awesome autocompletion library `Jedi`. @@ -32,7 +46,7 @@ jedi-vim is a is a Vim binding to the awesome autocompletion library `Jedi`. - Support for goto and renaming. ============================================================================== -2. Installation *jedi-vim-installation* +2. Installation *jedi-vim-installation* Get the latest from http://github.com/davidhalter/jedi-vim. @@ -57,79 +71,191 @@ On Arch Linux, you can also install jedi-vim from AUR, with the `vim-jedi` package. ============================================================================== -3. Support *jedi-vim-support* +3. Support *jedi-vim-support* The Jedi library supports most of Python's core features. From decorators to generators, there is broad support. ============================================================================== -4. Usage *jedi-vim-usage* +4. Usage *jedi-vim-usage* The autocompletion can be used with , if you want it to work with you can use the Supertab plugin. ============================================================================== -5. Mappings *jedi-vim-mappings* +5. Key Bindings *jedi-vim-keybindings* + +All keybindings can be mapped by setting the appropriate global option. For +example, to set the keybinding for starting omnicompletion to instead of +, add the following setting to your .vimrc file: > + + let g:jedi#autocompletion_command = "" + +Note: If you have |g:jedi#auto_initialization| set to 0, you have to create +the mappings yourself by calling the corresponding functions: > + + " Using for omnicompletion + inoremap + " Use r (by default <\-r>) for renaming + nnoremap r :call jedi#rename() + " etc. + +------------------------------------------------------------------------------ +5.1. `g:jedi#autocompletion_command` *g:jedi#autocompletion_command* +Function: n/a; see above +Default: Start completion + +Starts completion. + +------------------------------------------------------------------------------ +5.2. `g:jedi#goto_command` *g:jedi#goto_command* +Function: `jedi#goto()` +Default: g Go to definition + +This finds the first definition of the function/class under the cursor. + +------------------------------------------------------------------------------ +5.3. `g:jedi#get_definition_command` *g:jedi#get_definition_command* +Function: `jedi#get_definition()` +Default: d Go to original definition + +This command tries to find the original definition of the function/class under +the cursor. If the function is e.g. imported from another module, this tries +to follow the "import chain" to the end. It does not work with modules written +in C. + +------------------------------------------------------------------------------ +5.4. `g:jedi#pydoc` *g:jedi#pydoc_command* +Function: `jedi#show_pydoc()` +Default: Show pydoc documentation + +This shows the pydoc documentation for the item currently under the cursor. +The documentation is opened in a horizontally split buffer. + +------------------------------------------------------------------------------ +5.5. `g:jedi#rename_command` *g:jedi#rename_command* +Function: `jedi#rename()` +Default: r Rename variables + +Jedi-Vim deletes the word currently under the cursor and puts Vim in insert +mode, where the user is expected to enter the new variable name. Upon leaving +insert mode, Jedi-Vim then renames all occurences of the old variable name +with the new one. The number of renames is displayed in the command line. + +------------------------------------------------------------------------------ +5.6. `g:jedi#related_names_command` *g:jedi#related_names_command* +Function: `jedi#related_names()` +Default: n Show related names + +The quickfix window is populated with a list of all names which point to the +definition of the name under the cursor. ============================================================================== -6. Configuration *jedi-vim-configuration* +6. Configuration *jedi-vim-configuration* -Jedi is by default automatically initialized. If you don't want that I suggest -you disable the auto-initialization in your .vimrc: > +------------------------------------------------------------------------------ +6.1. `g:jedi#auto_initialization` *g:jedi#auto_initialization* - let g:jedi#auto_initialization = 0 +Upon initialization, Jedi-Vim performs the following steps: -There are also some Vim options (like completeopt) which are automatically -initialized, if you don't want that: > +1. Set the current buffers 'omnifunc' to its own completion function + `jedi#complete` +2. Create mappings to commands specified in |jedi-vim-mappings| +3. Call `jedi#configure_function_definition()` if + `g:jedi#show_function_definition` is set - let g:jedi#auto_vim_configuration = 0 +You can disable the default initialization routine by setting this option to +0. Beware that you have to perform the above steps yourself, though. -The goto is by default on . If you want to change that: > +Options: 0 or 1 +Default: 1 (Perform automatic initialization) - let g:jedi#goto_command = "g" +------------------------------------------------------------------------------ +6.2. `g:jedi#auto_vim_configuration` *g:jedi#auto_vim_configuration* -get_definition is by default on . If you want to change that: > +Jedi-Vim sets 'completeopt' to `menuone,longest,preview` by default. It also +remaps to in insert mode. If you want to keep your own +configuration, disable this setting. - let g:jedi#get_definition_command = "d" +Options: 0 or 1 +Default: 1 (Set 'completeopt' and mapping as described above) -Showing the pydoc is by default on . If you want to change that: > +------------------------------------------------------------------------------ +6.3. `g:jedi#popup_on_dot` *g:jedi#popup_on_dot* - let g:jedi#pydoc = "K" +Jedi automatically starts completion upon typing a period in insert mode. -If you are a person who likes to use Vim buffers not tabs, you might want to -put that in your .vimrc: > +However, when working with large modules, this can slow down your typing flow +since you have to wait for Jedi to parse the module and show the completion +menu. By disabling this setting, completion is only started when you manually +press the completion key. - let g:jedi#use_tabs_not_buffers = 0 +Options: 0 or 1 +Default: 1 (Start completion on typing a period) -Jedi automatically starts the completion if you type a dot, e.g. "str.", if -you don't want this: > +------------------------------------------------------------------------------ +6.4. `g:jedi#popup_select_first` *g:jedi#popup_select_first* - let g:jedi#popup_on_dot = 0 +Upon starting completion, Jedi-Vim can automatically select the first entry +that pops up (but without actually inserting it). -Jedi selects the first line of the completion menu: for a better typing-flow and -usually saves one keypress. > +This leads to a better typing flow: As you type more characters, the entries +in the completion menu are narrowed down. If they are narrowed down enough, +you can just press to insert the first match. - let g:jedi#popup_select_first = 0 +Options: 0 or 1 +Default: 1 (Automatically select first completion entry) -There's some support for refactoring: > +------------------------------------------------------------------------------ +6.5. `g:jedi#auto_close_doc` *g:jedi#auto_close_doc* - let g:jedi#rename_command = "r" +When doing completion, Jedi-Vim shows the docstring of the currently selected +item in a preview window. This window is by default closed when inserting a +completion item. -And you can list all names that are related (have the same origin): > +Set this to 1 to leave the preview window open. This could be useful if you +want to browse longer docstrings. - let g:jedi#related_names_command = "n" +Options: 0 or 1 +Default: 1 (Automatically close preview window upon finishing completion) -If you want to change the default autocompletion command: > +------------------------------------------------------------------------------ +6.6. `g:jedi#show_function_definition` *g:jedi#show_function_def* - let g:jedi#autocompletion_command = "" +Vim-Jedi can display a small window detailing the arguments of the currently +completed function and highlighting the currently selected argument. This can +be disabled by setting this option to 0. -By default you get a window that displays the function definition you're -currently in. If you don't want that: > +Options: 0 or 1 +Default: 1 (Show function definition window) - let g:jedi#show_function_definition = "0" +Note: This setting is ignored if |g:jedi#auto_initialization| is set to 0. In +that case, if you want to see function definitions, you have to set this up +manually by calling a function in your configuration file: > + + call jedi#configure_function_definition() + +------------------------------------------------------------------------------ +6.7. `g:jedi#use_tabs_not_buffers` *g:jedi#use_tabs_not_buffers* + +By default, Jedi-Vim opens a new tab if you use the "go to", "show +definition", or "related names" commands. When you set this option to 0, they +open in the current buffer instead. + +Options: 0 or 1 +Default: 1 (Command output is put in a new tab) + +------------------------------------------------------------------------------ +6.8. `g:jedi#squelch_py_warning` *g:jedi#squelch_py_warning* + +When Vim has not been compiled with +python, Jedi shows a warning to that +effect and aborts loading itself. Set this to 1 to suppress that warning. + +Options: 0 or 1 +Default: 0 (Warning is shown) ============================================================================== -7. Contributing *jedi-vim-contributing* +7. Contributing *jedi-vim-contributing* If you have any comments or feature requests, please tell me! I really want to know, what you think about Jedi and jedi-vim. From 93e49bb88898019f94febabb5f461d39c11b021b Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Fri, 1 Mar 2013 20:12:53 +0100 Subject: [PATCH 4/9] Add install, intro, and features sections --- doc/jedi-vim.txt | 123 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 101 insertions(+), 22 deletions(-) diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index a1fcbdd..7965119 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -14,7 +14,11 @@ Contents *jedi-vim-contents* 1. Introduction |jedi-vim-introduction| 2. Installation |jedi-vim-installation| -3. Support |jedi-vim-support| + 2.0. Requirements |jedi-vim-installation-requirements| + 2.1. Manually |jedi-vim-installation-manually| + 2.2. Using Pathogen |jedi-vim-installation-pathogen| + 2.3. Using Vundle |jedi-vim-installation-vundle| +3. Supported Python features |jedi-vim-support| 4. Usage |jedi-vim-usage| 5. Mappings |jedi-vim-mappings| 5.1. Start completion |g:jedi#autocompletion_command| @@ -38,43 +42,118 @@ Contents *jedi-vim-contents* ============================================================================== 1. Introduction *jedi-vim-introduction* -jedi-vim is a is a Vim binding to the awesome autocompletion library `Jedi`. +jedi-vim is a is a Vim binding to the awesome Python autocompletion library +`Jedi`. Among Jedi's (and, therefore, Jedi-Vim's) features are: -- Completion for almost anything. -- Display of function/class bodies, docstrings. -- Pydoc support with highlighting. -- Support for goto and renaming. +- Completion for a wide array of Python features (see |jedi-vim-support|) +- Robust in dealing with syntax errors and wrong indentation +- Parses complex module/function/class structures +- Infers function arguments from Sphinx/Epydoc strings +- Doesn't execute Python code +- Supports Virtualenv +- Supports Python 2.5+ and 3.2+ + +By leveraging this library, Jedi-Vim adds the following capabilities to Vim: + +- Displaying function/class bodies +- "Go to definition" command +- Displaying docstrings +- Renaming and refactoring +- Looking up related names ============================================================================== 2. Installation *jedi-vim-installation* -Get the latest from http://github.com/davidhalter/jedi-vim. +------------------------------------------------------------------------------ +2.0. Requirements *jedi-vim-installation-requirements* -You can get the Jedi library at http://github.com/davidhalter/jedi. +First of all, Jedi-Vim requires Vim to be compiled with the `+python` option. -You might want to use Pathogen http://github.com/tpope/vim-pathogen to -install Jedi in Vim. Also you need Vim compiled with +python, which is -typical for most distributions on Linux. - -The first thing you need after that is an up-to-date version of Jedi. You can -either get it via > +The Jedi library has to be installed for Jedi-Vim to work properly. You can +install it first, by using your e.g. your distribution's package manager, or +by using pip: > pip install jedi -or with > +However, you can also install it as a git submodule if you don't want to use +Jedi for anything but this plugin. How to do this is detailed below. - git submodule update --init +------------------------------------------------------------------------------ +2.1. Installing manually *jedi-vim-installation-manually* -in your jedi-vim repository. +1a. Get the latest repository from Github: > -On Arch Linux, you can also install jedi-vim from AUR, with the `vim-jedi` -package. + git clone http://github.com/davidhalter/jedi-vim + +1b. If you want to install Jedi as a submodule, issue this command instead: +> + git clone --recursive http://github/davidhalter/jedi-vim + +2. Put the plugin files into their corresponding folders in your vim runtime + directory (usually ~/.vim). Be sure to pay attention to the directory + structure! +3. Update the Vim help tags with > + + :helptags /doc + +------------------------------------------------------------------------------ +2.1. Installing using Pathogen *jedi-vim-installation-pathogen* + +Pathogen simplifies installation considerably. + +1.a Clone the git repository into your bundles directory: > + + git clone http://github.com/davidhalter/jedi-vim + +1b. Again, if you want to install `Jedi` as a submodule, use this command + instead: > + + git clone --recursive http://github/davidhalter/jedi-vim + +------------------------------------------------------------------------------ +2.3. Installing using Vundle *jedi-vim-installation-vundle* + +1. Vundle automatically downloads subrepositories as git submodules, so you + will automatically get the Jedi library with the Jedi-Vim plugin. Add the + following to the correct section in your .vimrc file: > + + Bundle 'git://github.com/davidhalter/jedi-vim' + +2. Issue the following command in Vim: > + + :BundleInstall + +Help tags are generated automatically, so you should be good to go. ============================================================================== -3. Support *jedi-vim-support* +3. Supported Python features *jedi-vim-support* -The Jedi library supports most of Python's core features. From decorators to -generators, there is broad support. +The Jedi library does all the hard work behind the scenes. It supports a large +number of Python features to be completed, among them: + +- builtins +- multiple `return`s or `yield`s +- tuple assignments/array indexing/dictionary indexing +- `with`-statement/exception handling +- `*args`/`**kwargs` +- decorators/lambdas/closures +- generators/iterators +- some descriptors: `property`/`staticmethod`/`classmethod` +- some magic methods: `__call__`, `__iter__`, `__next__`, `__get__`, + `__getitem__`, `__init__` +- `list.append()`, `set.add()`, `list.extend()`, etc. +- (nested) list comprehensions/ternary expressions +- relative `import`s +- `getattr()`/`__getattr__`/`__getattribute__` +- function annotations (py3k feature, are ignored right now, but being parsed) +- class decorators (py3k feature, are being ignored too at the moment) +- simple/usual `sys.path` modifications +- `isinstance` checks for `if`/`while`/`assert` + case, that doesn’t work with Jedi) + +Note: This list is not necessarily up to date. For a complete list of +features, please refer to the Jedi documentation at +http://jedi.readthedocs.org. ============================================================================== 4. Usage *jedi-vim-usage* From 0d27821064029ac93dd627b12f4e4e0ce78551c5 Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Fri, 1 Mar 2013 20:31:36 +0100 Subject: [PATCH 5/9] Add usage section and goto/find_def explanation The usage section feels sort of superfluous. I don't know. >:( The distinction between jedi#goto() and jedi#fund_definition() was a bit unclear, so I expanded it a bit. --- doc/jedi-vim.txt | 39 +++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index 7965119..3d48807 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -158,8 +158,17 @@ http://jedi.readthedocs.org. ============================================================================== 4. Usage *jedi-vim-usage* -The autocompletion can be used with , if you want it to work with - you can use the Supertab plugin. +With the default settings, autocompletion can be triggered by typing +. The first entry will automatically be selected, so you can press + to insert it into your code or keep typing and narrow down your +completion options. The usual and / keybindings work as +well. Autocompletion is also triggered by typing a period in insert mode. +Since periods rarely occur in Python code outside of method/import lookups, +this is handy to have (but can be disabled). + +When it encounters a new module, Jedi might take a few seconds to parse its +contents. Afterwards, the contents are cached and completion will be almost +instantaneous. ============================================================================== 5. Key Bindings *jedi-vim-keybindings* @@ -191,7 +200,8 @@ Starts completion. Function: `jedi#goto()` Default: g Go to definition -This finds the first definition of the function/class under the cursor. +This function finds the first definition of the function/class under the +cursor. It produces an error if the definition is not in a Python file. ------------------------------------------------------------------------------ 5.3. `g:jedi#get_definition_command` *g:jedi#get_definition_command* @@ -199,9 +209,26 @@ Function: `jedi#get_definition()` Default: d Go to original definition This command tries to find the original definition of the function/class under -the cursor. If the function is e.g. imported from another module, this tries -to follow the "import chain" to the end. It does not work with modules written -in C. +the cursor. As for the previous function, it does not work if the definition +isn't in a Python source file. + +The difference between this and the previous function is that the previous +function doesn't perform recursive lookups. Take, for example, the following +structure: > + + # file1.py: + from file2 import foo + + # file2.py: + from file3 import bar as foo + + # file3.py + def bar(): + pass + +The `jedi#goto()` function will take you to the "from file2 import foo" +statement in file1.py, while the `jedi#get_definition()` function will take +you all the way to the "def bar():" line in file3.py. ------------------------------------------------------------------------------ 5.4. `g:jedi#pydoc` *g:jedi#pydoc_command* From 4c0652064a5ad077e1b22c71331a0ab625c02f7f Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Fri, 1 Mar 2013 20:39:13 +0100 Subject: [PATCH 6/9] Added blurb about configuration in .vimrc I don't know if this should even be in there because it seems kind of like a bug. --- doc/jedi-vim.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index 3d48807..4a8fc0b 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -259,6 +259,11 @@ definition of the name under the cursor. ============================================================================== 6. Configuration *jedi-vim-configuration* +Note: You currently have to set these options in your .vimrc. Setting them in +an ftplugin (e.g. ~/.vim/ftplugin/python/jedi-vim-settings.vim) will not work +because Jedi-Vim is not set up as an filetype plugin, but as a "regular" +plugin. + ------------------------------------------------------------------------------ 6.1. `g:jedi#auto_initialization` *g:jedi#auto_initialization* From a8726171bf1c7a25e9d951288c88e989a8d8373e Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Fri, 1 Mar 2013 21:11:50 +0100 Subject: [PATCH 7/9] Add license section --- doc/jedi-vim.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index 4a8fc0b..e6ad2fd 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -37,6 +37,7 @@ Contents *jedi-vim-contents* 6.7. use_tabs_not_buffers |g:jedi#use_tabs_not_buffers| 6.8. squelch_py_warning |g:jedi#squelch_py_warning| 7. Contributing |jedi-vim-contributing| +8. License |jedi-vim-license| ============================================================================== @@ -371,4 +372,9 @@ Default: 0 (Warning is shown) If you have any comments or feature requests, please tell me! I really want to know, what you think about Jedi and jedi-vim. +============================================================================== +8. License *jedi-vim-license* + +Jedi-Vim is licensed under the GNU LGPL v3 license or later. + vim: textwidth=78 tabstop=8 filetype=help:norightleft: From 31611335b4d88f3e8c5fc76f9380f8d278c52b99 Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Sat, 2 Mar 2013 04:58:47 +0100 Subject: [PATCH 8/9] Out of beta, yay --- README.rst | 2 -- doc/jedi-vim.txt | 1 - 2 files changed, 3 deletions(-) diff --git a/README.rst b/README.rst index 8d16e4c..5776117 100644 --- a/README.rst +++ b/README.rst @@ -2,8 +2,6 @@ jedi-vim - awesome Python autocompletion with VIM ################################################# -**now in beta testing phase** - *If you have any comments or feature requests, please tell me! I really want to know, what you think about Jedi and jedi-vim.* diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index e6ad2fd..d03f309 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -7,7 +7,6 @@ \______/ |_______||_______/ |__| \__/ |__| |__| |__|~ jedi-vim - awesome Python autocompletion with Vim - **now in beta testing phase** ============================================================================== Contents *jedi-vim-contents* From 354f8da568a65b420fdc94e8c2622f4a7de7b3b6 Mon Sep 17 00:00:00 2001 From: Patrice Peterson Date: Sat, 2 Mar 2013 05:17:09 +0100 Subject: [PATCH 9/9] Minor capitalization and awkward wording fixes - Replace all occurences of Jedi-Vim/Jedi with jedi-vim/jedi - Capitalize first letter on bullet points - oh god how do i english - Fix wrong description of g:jedi#auto_close_doc option --- doc/jedi-vim.txt | 143 ++++++++++++++++++++++++----------------------- 1 file changed, 73 insertions(+), 70 deletions(-) diff --git a/doc/jedi-vim.txt b/doc/jedi-vim.txt index d03f309..6ac01a8 100644 --- a/doc/jedi-vim.txt +++ b/doc/jedi-vim.txt @@ -42,8 +42,8 @@ Contents *jedi-vim-contents* ============================================================================== 1. Introduction *jedi-vim-introduction* -jedi-vim is a is a Vim binding to the awesome Python autocompletion library -`Jedi`. Among Jedi's (and, therefore, Jedi-Vim's) features are: +Jedi-vim is a is a Vim binding to the awesome Python autocompletion library +`jedi`. Among jedi's (and, therefore, jedi-vim's) features are: - Completion for a wide array of Python features (see |jedi-vim-support|) - Robust in dealing with syntax errors and wrong indentation @@ -53,7 +53,7 @@ jedi-vim is a is a Vim binding to the awesome Python autocompletion library - Supports Virtualenv - Supports Python 2.5+ and 3.2+ -By leveraging this library, Jedi-Vim adds the following capabilities to Vim: +By leveraging this library, jedi-vim adds the following capabilities to Vim: - Displaying function/class bodies - "Go to definition" command @@ -67,29 +67,29 @@ By leveraging this library, Jedi-Vim adds the following capabilities to Vim: ------------------------------------------------------------------------------ 2.0. Requirements *jedi-vim-installation-requirements* -First of all, Jedi-Vim requires Vim to be compiled with the `+python` option. +First of all, jedi-vim requires Vim to be compiled with the `+python` option. -The Jedi library has to be installed for Jedi-Vim to work properly. You can -install it first, by using your e.g. your distribution's package manager, or -by using pip: > +The jedi library has to be installed for jedi-vim to work properly. You can +install it first, by using e.g. your distribution's package manager, or by +using pip: > pip install jedi However, you can also install it as a git submodule if you don't want to use -Jedi for anything but this plugin. How to do this is detailed below. +jedi for anything but this plugin. How to do this is detailed below. ------------------------------------------------------------------------------ 2.1. Installing manually *jedi-vim-installation-manually* 1a. Get the latest repository from Github: > - git clone http://github.com/davidhalter/jedi-vim + git clone http://github.com/davidhalter/jedi-vim path/to/bundles/jedi-vim -1b. If you want to install Jedi as a submodule, issue this command instead: -> - git clone --recursive http://github/davidhalter/jedi-vim +1b. If you want to install jedi as a submodule instead, issue this command: > -2. Put the plugin files into their corresponding folders in your vim runtime + git clone --recursive http://github/davidhalter/jedi-vim + +2. Put the plugin files into their respective folders in your vim runtime directory (usually ~/.vim). Be sure to pay attention to the directory structure! 3. Update the Vim help tags with > @@ -103,53 +103,55 @@ Pathogen simplifies installation considerably. 1.a Clone the git repository into your bundles directory: > - git clone http://github.com/davidhalter/jedi-vim + git clone http://github.com/davidhalter/jedi-vim path/to/bundles/jedi-vim -1b. Again, if you want to install `Jedi` as a submodule, use this command +1b. Again, if you want to install jedi as a submodule, use this command instead: > - git clone --recursive http://github/davidhalter/jedi-vim + git clone --recursive http://github/davidhalter/jedi-vim ------------------------------------------------------------------------------ 2.3. Installing using Vundle *jedi-vim-installation-vundle* 1. Vundle automatically downloads subrepositories as git submodules, so you - will automatically get the Jedi library with the Jedi-Vim plugin. Add the - following to the correct section in your .vimrc file: > + will automatically get the jedi library with the jedi-vim plugin. Add the + following to the Bundles section in your .vimrc file: > - Bundle 'git://github.com/davidhalter/jedi-vim' + Bundle 'git://github.com/davidhalter/jedi-vim' 2. Issue the following command in Vim: > - :BundleInstall + :BundleInstall Help tags are generated automatically, so you should be good to go. ============================================================================== 3. Supported Python features *jedi-vim-support* -The Jedi library does all the hard work behind the scenes. It supports a large -number of Python features to be completed, among them: +The jedi library does all the hard work behind the scenes. It supports +completion of a large number of Python features, among them: -- builtins -- multiple `return`s or `yield`s -- tuple assignments/array indexing/dictionary indexing +- Builtins +- Multiple `return`s or `yield`s +- Tuple assignments/array indexing/dictionary indexing - `with`-statement/exception handling -- `*args`/`**kwargs` -- decorators/lambdas/closures -- generators/iterators -- some descriptors: `property`/`staticmethod`/`classmethod` -- some magic methods: `__call__`, `__iter__`, `__next__`, `__get__`, +- `*args` and `**kwargs` +- Decorators, lambdas, closures +- Generators, iterators +- Some descriptors: `property`/`staticmethod`/`classmethod` +- Some magic methods: `__call__`, `__iter__`, `__next__`, `__get__`, `__getitem__`, `__init__` - `list.append()`, `set.add()`, `list.extend()`, etc. -- (nested) list comprehensions/ternary expressions -- relative `import`s +- (Nested) list comprehensions and ternary expressions +- Relative `import`s - `getattr()`/`__getattr__`/`__getattribute__` -- function annotations (py3k feature, are ignored right now, but being parsed) -- class decorators (py3k feature, are being ignored too at the moment) -- simple/usual `sys.path` modifications -- `isinstance` checks for `if`/`while`/`assert` - case, that doesn’t work with Jedi) +- Function annotations (py3k feature, are being ignored at the moment, but are + parsed) +- Class decorators (py3k feature, are being ignored at the moment, but are + parsed) +- Simple/usual `sys.path` modifications +- `isinstance` checks for `if`/`while`/`assert` case, that doesn’t work with + Jedi Note: This list is not necessarily up to date. For a complete list of features, please refer to the Jedi documentation at @@ -166,9 +168,9 @@ well. Autocompletion is also triggered by typing a period in insert mode. Since periods rarely occur in Python code outside of method/import lookups, this is handy to have (but can be disabled). -When it encounters a new module, Jedi might take a few seconds to parse its -contents. Afterwards, the contents are cached and completion will be almost -instantaneous. +When it encounters a new module, jedi might take a few seconds to parse that +module's contents. Afterwards, the contents are cached and completion will be +almost instantaneous. ============================================================================== 5. Key Bindings *jedi-vim-keybindings* @@ -180,7 +182,7 @@ example, to set the keybinding for starting omnicompletion to instead of let g:jedi#autocompletion_command = "" Note: If you have |g:jedi#auto_initialization| set to 0, you have to create -the mappings yourself by calling the corresponding functions: > +a mapping yourself by calling a function: > " Using for omnicompletion inoremap @@ -193,7 +195,7 @@ the mappings yourself by calling the corresponding functions: > Function: n/a; see above Default: Start completion -Starts completion. +Performs autocompletion (or omnicompletion, to be precise). ------------------------------------------------------------------------------ 5.2. `g:jedi#goto_command` *g:jedi#goto_command* @@ -209,12 +211,12 @@ Function: `jedi#get_definition()` Default: d Go to original definition This command tries to find the original definition of the function/class under -the cursor. As for the previous function, it does not work if the definition -isn't in a Python source file. +the cursor. Just like the `jedi#goto()` function, it does not work if the +definition isn't in a Python source file. -The difference between this and the previous function is that the previous -function doesn't perform recursive lookups. Take, for example, the following -structure: > +The difference between `jedi#goto()` and `jedi#get_definition()` is that the +former doesn't perform recursive lookups. Take, for example, the following +module structure: > # file1.py: from file2 import foo @@ -243,10 +245,11 @@ The documentation is opened in a horizontally split buffer. Function: `jedi#rename()` Default: r Rename variables -Jedi-Vim deletes the word currently under the cursor and puts Vim in insert +Jedi-vim deletes the word currently under the cursor and puts Vim in insert mode, where the user is expected to enter the new variable name. Upon leaving -insert mode, Jedi-Vim then renames all occurences of the old variable name -with the new one. The number of renames is displayed in the command line. +insert mode, jedi-vim then renames all occurences of the old variable name +with the new one. The number of performed renames is displayed in the command +line. ------------------------------------------------------------------------------ 5.6. `g:jedi#related_names_command` *g:jedi#related_names_command* @@ -261,13 +264,13 @@ definition of the name under the cursor. Note: You currently have to set these options in your .vimrc. Setting them in an ftplugin (e.g. ~/.vim/ftplugin/python/jedi-vim-settings.vim) will not work -because Jedi-Vim is not set up as an filetype plugin, but as a "regular" +because jedi-vim is not set up as an filetype plugin, but as a "regular" plugin. ------------------------------------------------------------------------------ 6.1. `g:jedi#auto_initialization` *g:jedi#auto_initialization* -Upon initialization, Jedi-Vim performs the following steps: +Upon initialization, jedi-vim performs the following steps: 1. Set the current buffers 'omnifunc' to its own completion function `jedi#complete` @@ -284,7 +287,7 @@ Default: 1 (Perform automatic initialization) ------------------------------------------------------------------------------ 6.2. `g:jedi#auto_vim_configuration` *g:jedi#auto_vim_configuration* -Jedi-Vim sets 'completeopt' to `menuone,longest,preview` by default. It also +Jedi-vim sets 'completeopt' to `menuone,longest,preview` by default. It also remaps to in insert mode. If you want to keep your own configuration, disable this setting. @@ -294,10 +297,10 @@ Default: 1 (Set 'completeopt' and mapping as described above) ------------------------------------------------------------------------------ 6.3. `g:jedi#popup_on_dot` *g:jedi#popup_on_dot* -Jedi automatically starts completion upon typing a period in insert mode. +Jedi-vim automatically starts completion upon typing a period in insert mode. However, when working with large modules, this can slow down your typing flow -since you have to wait for Jedi to parse the module and show the completion +since you have to wait for jedi to parse the module and show the completion menu. By disabling this setting, completion is only started when you manually press the completion key. @@ -307,8 +310,8 @@ Default: 1 (Start completion on typing a period) ------------------------------------------------------------------------------ 6.4. `g:jedi#popup_select_first` *g:jedi#popup_select_first* -Upon starting completion, Jedi-Vim can automatically select the first entry -that pops up (but without actually inserting it). +Upon starting completion, jedi-vim can automatically select the first entry +that pops up (without actually inserting it). This leads to a better typing flow: As you type more characters, the entries in the completion menu are narrowed down. If they are narrowed down enough, @@ -320,20 +323,20 @@ Default: 1 (Automatically select first completion entry) ------------------------------------------------------------------------------ 6.5. `g:jedi#auto_close_doc` *g:jedi#auto_close_doc* -When doing completion, Jedi-Vim shows the docstring of the currently selected -item in a preview window. This window is by default closed when inserting a -completion item. +When doing completion, jedi-vim shows the docstring of the currently selected +item in a preview window. By default, this window is being closed after +insertion of a completion item. -Set this to 1 to leave the preview window open. This could be useful if you -want to browse longer docstrings. +Set this to 1 to leave the preview window open even after leaving insert mode. +This could be useful if you want to browse longer docstrings. Options: 0 or 1 -Default: 1 (Automatically close preview window upon finishing completion) +Default: 1 (Automatically close preview window upon leaving insert mode) ------------------------------------------------------------------------------ 6.6. `g:jedi#show_function_definition` *g:jedi#show_function_def* -Vim-Jedi can display a small window detailing the arguments of the currently +Jedi-vim can display a small window detailing the arguments of the currently completed function and highlighting the currently selected argument. This can be disabled by setting this option to 0. @@ -341,7 +344,7 @@ Options: 0 or 1 Default: 1 (Show function definition window) Note: This setting is ignored if |g:jedi#auto_initialization| is set to 0. In -that case, if you want to see function definitions, you have to set this up +that case, if you want to see function definitions, you have to set it up manually by calling a function in your configuration file: > call jedi#configure_function_definition() @@ -349,7 +352,7 @@ manually by calling a function in your configuration file: > ------------------------------------------------------------------------------ 6.7. `g:jedi#use_tabs_not_buffers` *g:jedi#use_tabs_not_buffers* -By default, Jedi-Vim opens a new tab if you use the "go to", "show +By default, jedi-vim opens a new tab if you use the "go to", "show definition", or "related names" commands. When you set this option to 0, they open in the current buffer instead. @@ -359,7 +362,7 @@ Default: 1 (Command output is put in a new tab) ------------------------------------------------------------------------------ 6.8. `g:jedi#squelch_py_warning` *g:jedi#squelch_py_warning* -When Vim has not been compiled with +python, Jedi shows a warning to that +When Vim has not been compiled with +python, jedi-vim shows a warning to that effect and aborts loading itself. Set this to 1 to suppress that warning. Options: 0 or 1 @@ -368,12 +371,12 @@ Default: 0 (Warning is shown) ============================================================================== 7. Contributing *jedi-vim-contributing* -If you have any comments or feature requests, please tell me! I really want -to know, what you think about Jedi and jedi-vim. +If you have any comments or feature requests, please tell me! I really want to +know what you think about jedi and jedi-vim. ============================================================================== 8. License *jedi-vim-license* -Jedi-Vim is licensed under the GNU LGPL v3 license or later. +Jedi-vim is licensed under the GNU LGPL v3 license or later. vim: textwidth=78 tabstop=8 filetype=help:norightleft: