rope_py3k / docs / tutorial.txt

 Rope Tutorial

.. contents::


Right now most of rope's development efforts are toward developing
core parts and not the UI.  Because of this UI parts don't look very
user friendly and there is no documentation or help for the UI
parts.  For this reason I think the best way for learning more about
rope is using it and trying its menu items.

This tutorial merely tries to demonstrate how to use rope for basic
editing tasks.  This tutorial attempts to give a fast overview of
rope and some of its basic features.  It covers things like opening
projects, creating and editing files.  Read `where to go next`_
section for more information.

Starting Rope

Simply run the ```` included in the root of the package::


Creating And Opening Projects

To create or open a project select the ``Open Project`` from the file
menu.  You will be asked about the location of the root (toplevel)
folder of your project.

Making Files And Folders

Consider we want to make a hierarchy like this::


In order to make this project tree, after opening the project you
can use the following table.

====================  ==================  =================
Selected Menu Item    Parent Folder       File/Folder Name
====================  ==================  =================
File.New File                             file1.txt
File.New Folder                           folder1
File.New File         folder1             file2.txt
File.New Folder       folder1             folder2
File.New File         folder1/folder2     file3.txt
====================  ==================  =================

Note that for making ``file3.txt`` we've used ``/`` as a directory
separator.  You should always use ``/`` as directory separator
regardless of the operating system you are running rope on.

Making Modules and Packages

Consider we want to make a hierarchy like this::


In order to make this project tree, after opening the project you
can use the following table.

====================  ==================  ====================
Selected Menu Item    Source Folder       Module/Package Name
====================  ==================  ====================
File.New Module                           mod1
File.New Package                          pkg1
File.New Module                           pkg1.mod2
File.New package                          pkg1.pkg2
File.New Module                           pkg1.pkg2.mod3
File.New Folder                           src
File.New Module       src                 mod4
====================  ==================  ====================

Opening Files

You can select the ``Find File`` item from the ``File`` menu or use
``C-x C-f``.  In the `Find File` dialog use the name of the file or
module to find it.  The dialog shows all files that start with the
given name.  Press enter to open the file.

In the find file dialog, you can use ``/``\s to match parent folders.
For instance for opening ``rope/base/`` you can use
``base/`` or ``ba*/__``.

Saving A File

Use ``C-x C-s`` to save the contents of the active editor.

Changing Editor

With rope you can open and edit many files at the same time.  To switch
between open editors you can use ``C-x b``.

Closing An Editor

Use ``C-x k`` to close active editor.

Emacs Keybindings

*rope* uses emacs keybindings most of the time.  For example in most of
the dialogs like ``code assist`` or ``outline`` you can use ``C-n``
and ``C-p`` to move over the items.

Copying And Cutting

Select the beginning of the region you want to copy or cut by moving
the cursor on it and pressing ``Ctrl-space``.  Then move the cursor to
the end of that region and use ``Alt-w`` or ``Ctrl-w`` for copying or

For pasting move the cursor to the place you want to paste and press

Undoing Actions

Rope comes with two kinds of undo/redos.

* Undo/redoing editing

  You can undo/redo the editing changes using ``C-x u``/``C-x r``.

* Undo/redoing project changes

  Project changes are the changes made to the files in the project.
  These changes consist of things like saving files, creating files/
  folders and refactoring.  You can undo/redo project changes using
  ``C-x p u``/``C-x p r``.

ReStructuredText Files

All ``*.txt`` files are considered to be in `ReST` format and are

Editing Python Files

Rope considers all ``*.py`` files to be python files.  It highlights
them and makes features like auto-completion, goto definition,
show doc, quick outline, refactorings and ... available.

Where To Go Next

The best way to learn about rope features is to use the features.
Have a look and try menu items.  The default keybinding for each
menu item is written in front of them.  For example `Code` menu
contains the entry `Code Assist (Auto-Complete)  M-slash`.  This means
you can use rope's auto-complete feature by pressing `alt` and
`/` keys.  Note that some of the menu items disappear when you're
not editing a file suitable for performing that action.  For example
code assist command is only active when editing a python file.

Have a look at `overview.txt`_ for an overview of some of rope's
features.  If you really want to see what rope can do, have a
look at the unit tests in the `ropetest` package.

.. _overview.txt: overview.html