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)

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

The best usage information I've found is a readme in the ropemacs source, here:

https://github.com/python-rope/ropemacs

You can set the root folder with rope-open-project . Once you've set the root project a .ropeproject dir will be created.

Inside it, a config.py file has hooks where you can run (python) code once the project is set. The project_opened(project): function is a good place to run code. I usually activate the virtual environment imp.load_source('/path-to-env/activate_this.py') , so that I can get source coverage for other libs in the virtual env.

For general usage of the rope library that ropemacs depends on, then check out:

Rope Overview

It describes in some detail what each of the refactorings does such as extract method. Note that according to the author this doc is a bit outdated. However, it should provide enough of an intro to ropes' features to get started.

To execute the ropemacs commands in Emacs, you can try one or more of the following:

1. Use the 'Keybinding' section in the README docs link from freyley's answer as a guide to learn the the mappings.
2. If you can't remember the keybindings, then execute M-x rope-<specific command name> and fill in the related refactoring name. For example, extract method would be M-x rope-extract-method.
3. Select in Emacs <menu-bar> -> Rope. For example, for extract method then select <menu-bar> -> Rope -> Refactorings -> Extract Method. It will also show you the associated keybindings (e.g. C-c r m)