rope_py3k / docs / tutorial.txt

===============
 Rope Tutorial
===============

.. contents::

Overview
========

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 ``rope.py`` included in the root of the package::

  python rope.py


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::

  project/
    file1.txt
    folder1/
      file2.txt
      folder2/
        file3.txt

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::

  project/
    mod1.py
    pkg1/
      __init__.py
      mod2.py
      pkg2/
        __init__.py
        mod3.py
    src/
       mod4.py


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/__init__.py`` you can use
``base/__init__.py`` 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
cutting.

For pasting move the cursor to the place you want to paste and press
``Ctrl-y``.


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
highlighted.


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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.