ropemacs USAGE tutorial
There are many sites with instructions on installing ropemacs, but so far I couldn't find any with instructions on how to use it after it's already installed. I have it installed, or at least it seems so, Emacs has "Rope" menu in it's top menu bar. Now what? So far I could use only "Show documentation" (C-c d by default). An attempt to use code assist (which is auto-complete, I presume?) only causes Emacs to ask about "Rope project root folder" (what's that?) in the minibuffer and then showing nothing.
So, once ropemacs is installed, what are the steps to see it in action on some simple python scripts? Something like "if you have this script in your emacs and put the blinking square here and press this, it does that" would be an answer.
(I've been thinking if I should ask this or not for some time, because nobody else seems to have the same problem)
Answer
Well, you first need to select your project root folder. Quite simply, this is the folder at the top level of your project, or the current folder if you're dealing with a single file. Once you've selected the root folder, then other options will work, such as code assist, showing documentation, jumping to other symbols, etc.
For full benefit of ropemacs, I suggest getting autocomplete.el, putting it in ~/.emacs.d, and then adding this to your .emacs
(add-to-list 'load-path "~/.emacs.d/")
(add-to-list 'load-path "~/.emacs.d/auto-complete-1.2")
(autoload 'python-mode "python-mode" "Python Mode." t)
(add-to-list 'auto-mode-alist '("\\.py\\'" . python-mode))
(add-to-list 'interpreter-mode-alist '("python" . python-mode))
(require 'python-mode)
(autoload 'pymacs-apply "pymacs")
(autoload 'pymacs-call "pymacs")
(autoload 'pymacs-eval "pymacs" nil t)
(autoload 'pymacs-exec "pymacs" nil t)
(autoload 'pymacs-load "pymacs" nil t)
(pymacs-load "ropemacs" "rope-")
(setq ropemacs-enable-autoimport t)
(require 'auto-complete)
(global-auto-complete-mode t)
This assumes you install autocomplete in ~/.emacs.d/auto-complete-1.2. After you do this, you will get autocomplete automatically after typing a few characters of a word or symbol.
You can modify your ROOT/.ropeproject/config.py file to add more directories to the rope lookup path, in order to provide better autocomplete.
EDIT: Two of the most important functions for me are looking up documentation and jumping directly to a function definition. This is dependent on setting the rope lookup path correctly for your project as mentioned above.
Documentation: Put the cursor over a symbol (function name, class name, etc), and do:
C-c d
This will show you the docstring for the symbol in question.
Jumping to definition:Put the cursor over a symbol (function name, class name, etc), and do:
C-c g
This will immediately open the file where the symbol resides and jump to the beginning of the definition. This is great for times when the documentation is sparse and you want to see the actual code. Also, it's really nice for navigating around inside your own code.
Find occurrences:
C-c f
Smart search in your entire project for the symbol at the cursor.
Code assist:
M-/
Just type the first characters of a function, class, etc, and this will show a list of possible completions. Note that due to python's nature, it will not always be a complete list.
Refactorings: There are quite a few options under Rope->Refactor. These are to organize your code better. How to use them should be mostly self-explanatory; in general, select the region of code you want to refactor, then choose the command.
Edit: In response to a comment below, here's exactly how to add other paths to your python path so autocomplete will look for those symbols as well.
prefs.add('python_path', '~/path/to/virtualenv/lib/python2.6/site-packages')
This goes in .ropeproject/config.py