ropemacs USAGE tutorial

Question

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)

Salamis

Answer 1

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

Sibyls

This does not help answer the question at all. Repeat, how do you use ropemacs. You haven't even said how the root folder is selected. – Unheardof

blokely, you already know how to select the root project folder. Emacs was already prompting you for it... – Sibyls

Also, I've given you the best advice on "how to use" ropemacs. In my opinion, the best way to use it, is to use it together with autocomplete. When you do that, you don't even have to know much about it, it's just there in the background founding completions for you. – Sibyls

There, I've added several basic commands. Really, this is much, much better than any advice I found on how to use it, so I hope it helps. – Sibyls

Does that mean that the code assist will work only for the symbols inside the "project root folder"? Would be kinda disappointing, if so... – Salamis

No, it should work on anything on your python path, though I've only used it in conjunction with virtualenv. For virtualenv, you can do something like this: prefs.add('python_path', '~/path/to/virtualenv/lib/python2.6/site-packages') – Sibyls

Oh, I got it. I just need to press TAB in the mini-buffer after I press M-/, or type a part of the symbol I'm looking for and then press TAB. Before I was trying to use M-/ right after I type, for instance, "Image.", then it was displaying "Completion for Image.:" and nothing else, which, I thought, meant that it couldn't find any completion. – Salamis

How do you go back(navigate back) after you looked at a symbol's definition. – Sulphathiazole

Is it possible to set project root folder by defualt on the .emacs setup? – Deland

Answer 2

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

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

Tuckerbag

it seems like the README.txt file has been moved to this directory bitbucket.org/agr/ropemacs/src – Pram

Answer 3

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.

Routinize

more info on setting up virutalenvs. – Abominate

rope-open-project does not exist when I do M-x – Deland

Answer 4

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)

Villalba