Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

docs update

  • Loading branch information...
commit d0dc71dd10bcb57ef8f4285dfad66533a14e9e1f 1 parent 93a68ed
@fdev31 fdev31 authored
Showing with 85 additions and 79 deletions.
  1. +39 −34 doc/python.rst
  2. +46 −45 doc/start.rst
View
73 doc/python.rst
@@ -2,14 +2,15 @@ Python plugin
=============
Strictly for the sake of this plugin I started Snaked's development. It requires
-`rope <http://rope.sourceforge.net/>`_ for it's work.
+`rope <http://rope.sourceforge.net/>`_ for it to work.
Pretty editor title formating
-----------------------------
-Package modules are presented like `package.module` or `package` instead
-`module.py` or `__init__.py`. Very useful extension to distinguish similar file
-names. Must have for every Pytonier.
+Changes tabs' display, uses package modules names, instead of filenames.
+Example: `module.py` or `__init__.py` is shown as `package.module` or `package`.
+It's a very useful extension to distinguish similar file
+names and is a must have for every Pytonista.
.. _python-goto-definition:
@@ -36,13 +37,13 @@ Or if rope can infer ``param`` type you can place cursor there and hit ``F3``.
Code completion
---------------
-Snaked uses gtksourceview2's completion framework. I've only implement python
-provider. All UI work are done by gtksourceview.
+Snaked uses gtksourceview2's completion framework. I just implemented the python
+provider. Most of the UI work is done by gtksourceview.
.. image:: /images/complete.*
-``<ctrl>space`` activates popup. Also there is support for showing pydocs in
-detailed proposal information.
+``<ctrl>space`` activates a popup. There is support for
+showing pydocs (docstrings) using `Details...` button.
.. _python-outline:
@@ -50,7 +51,7 @@ detailed proposal information.
Outline navigation
------------------
-This dialog provides easy jumping into needed module block.
+This dialog allow easy jumping to module' blocks.
.. image:: /images/outline1.*
@@ -62,11 +63,11 @@ This dialog provides easy jumping into needed module block.
Type hints
----------
-This is the most exiting Snaked's part. It allows to provide additional type
-information to rope for better type inferring and as consequence better
+This is the most exiting Snaked part. It allows you to provide additional type
+information to rope for a better type inferring and as consequence, better
completion and code navigation.
-What hints can be provided:
+Hints that can be provided:
* Function/method param types.
@@ -81,11 +82,13 @@ Usage
*****
There is special file to configure hints: ``.ropeproject/ropehints.py`` in your
-project root. It is ordinary python file which must define function
+project root. It is an ordinary python file which must define the function
``init(provider)``, where ``provider`` is default project hint provider with
build-in scope matcher and doc string hint support.
-Take note, without configured hints you have doc string hint provider anyway.
+.. note::
+
+ Without any configured hints you still have the doc string hint provider.
Snaked's hint providers
@@ -113,7 +116,7 @@ Snaked's scope matchers
Django hints
************
-Look at image:
+Look at the image:
.. image:: /images/django-hints.*
@@ -124,9 +127,9 @@ Cool, isn't it? Simply add django support into your ``.ropeproject/ropehints.py`
add_django_support(provider)
.. note::
- Django hints were developed against django 0.97 (yeah, I maintain such old
- project) codebase and not tested on current versions. Get me know if you
- will have any issues.
+ Django hints were developed against django 0.97 codebase (yeah, I maintain such old
+ project) and not tested on current versions. Get me know if you
+ encounter any issues.
PyGtk hints
***********
@@ -135,7 +138,7 @@ Image again:
.. image:: /images/pygtk-hints.*
-Who is there? ``BuilderAware`` is a simple wrapper which delegates missing
+Who is there? ``BuilderAware`` is a simple wrapper that delegates missing
attributes to GtkBuilder. ``Window`` is ``BuilderAware`` class constructed from
glade file. ``vbox1`` is a GtkVBox defined in glade file and PyGtk hint provider
resolves class attributes from it.
@@ -143,8 +146,8 @@ resolves class attributes from it.
Besides that, goto definition (``F3``) opens glade file and place cursor at
``vbox1`` declaration.
-And more, if there are any signal handlers in glade file they parameters also
-will be resolved.
+And more, if there are any signal handlers in glade file their parameters will also
+be resolved.
You only need to add pygtk support and assign glade file to class via
``ropehints.py``::
@@ -153,7 +156,7 @@ You only need to add pygtk support and assign glade file to class via
from snaked.plugins.python.pygtkhints import add_gtk_support
add_gtk_support(provider)
-And define glade file in class pydoc::
+And declare the glade filename in class' docstring::
class Window(BuilderAware):
"""glade-file: main.glade"""
@@ -165,28 +168,30 @@ Unit testing
This is a holy grail of modern development. Honestly, I didn't plan to integrate
unit testing support in snaked -- running ``py.test`` from terminal completely
-satisfied my needs, but during heavy tests reorganization I realized too much
-time was spent for snaked/terminal switching and searching fail's cause in
+satisfy my requirements, but during heavy tests reorganization I realized too much
+time was spent for snaked/terminal switching and searching failure's causes in
``py.test`` output.
-Plugin completely based on `py.test <http://pytest.org>`_ capabilities and you
-need latest (2.0) its version. Unit testing features:
+This plugin is completely based on `py.test <http://pytest.org>`_ capabilities.
+The latest version (2.0) is required.
+
+Unit testing features:
-* Test framework agnostic. Really killer feature -- one shoot and three bunnies
+* Test framework agnostic. A killer feature, really -- one shoot and three bunnies
are dead: ``py.test`` itself, `unittest
<http://docs.python.org/library/unittest.html>`_ and `nose
<http://somethingaboutorange.com/mrl/projects/nose/>`_.
-* Test environment configuration are done by ordinary ``conftest.py`` and
+* Test environment configuration is done by ordinary ``conftest.py`` and
`pytest.ini <http://pytest.org/customize.html>`_.
* Common GUI for testing process which can be founded in other IDEs.
* Tests output is not messed and can be seen for each test individually (thanks
- for ``py.test``).
+ to ``py.test``).
-* Quick jump to test fail cause. Also one can navigate through traceback.
- Without any mouse, fast ant easy.
+* Quick jump to test failure cause. Also one can navigate through traceback
+ without relying on mouse clicks, fast ant easy.
.. image:: /images/unittest.*
@@ -198,11 +203,11 @@ Shortcuts
* ``<ctrl>F10`` runs tests defined in scope under cursor. It can be test
function/method, test case class or whole module.
-* ``<shift><alt>x`` reruns last tests.
+* ``<shift><alt>x`` re-runs last tests.
* ``<alt>1`` toggles test result window.
-* ``Enter`` in test list view jums to failed test line.
+* ``Enter`` in test list view jumps to failed test line.
* ``<alt>u``/``<alt>n`` mnemonics navigate through traceback.
@@ -221,4 +226,4 @@ Then you should tell ``py.test`` which modules are tests proper. Create
[pytest]
python_files = tests.py
-That's all. Now you can run django tests with ``py.test`` and snaked.
+That's all. Now you can run django tests with ``py.test`` and snaked.
View
91 doc/start.rst
@@ -1,7 +1,7 @@
Getting started
===============
-This section explains how to start Snaked, perform basic editing and configure
+This section explains how to start Snaked, perform basic editing tasks and configure
it.
Running
@@ -16,7 +16,7 @@ You can run it either from terminal or run dialog::
allow one open first file.
-This command will run snaked with specified file::
+This command will start snaked with a specified file opened::
snaked /tmp/first_snaked_file.py
@@ -26,9 +26,9 @@ This command will run snaked with specified file::
.. note::
- Specified file do not need to exist. Snaked will create it after first save.
+ Specified file do not need to exist. Snaked will create it automatically on save operation.
-You can give several filenames to snaked::
+You can provide several filenames to snaked::
snaked /tmp/first_snaked_file.py /tmp/second_snaked_file.py
@@ -44,51 +44,55 @@ One can switch tabs on ``<alt>Left``/``<alt>Right`` keys.
Project navigation
------------------
-But specifying file names every time is too annoying, how can one open project
-file from Snaked itself? Solution is `Quick Open` dialog. Default shortcut
+Since specifying file names every time is too annoying, how one can open project
+file from Snaked itself?
+The solution is `Quick Open` dialog. Default shortcut
``<ctrl><alt>r``:
.. image:: /images/quick-open.*
-Here it is very common Snaked dialog -- search entry at of the top and list view
-below. It is used for preferences finding and python outline navigation also.
+Here is a very common Snaked dialog -- search entry at of the top and list view
+below. It is also used for preferences finding and python outline navigation.
-Behavior is very simple: you type several characters of subject to find,
+Behavior is very simple: you type several characters contained in the name you search,
"``se``" in my case and dialog shows variants to select. ``Up``/``Down``
navigate between items, ``Enter`` activates selection, ``<alt>s`` focuses search
-entry again. Also if there is only the one item you can press ``Enter`` without
-need to put focus on list view.
+entry again.
+
+.. note::
+ If there is only one item in the list you can press ``Enter`` without
+ setting the focus on the list view.
`Quick Open` searches files only in current project
following these matching rules:
-* filename starts with search term.
+* filename starts with the search term.
-* filename contains search term
+* filename contains the search term
-* file path contains search term
+* file path contains the search term
* fuzzy match. if search term contains slashes it matches similar file paths. For
example ``pl/py`` will match ``plugin/python/__init__.py`` or
``plugin/name/python.py``
If search entry is empty, `browser mode` is activated. With it you can investigate
-project structure in more common way: ``Enter`` opens directory content and
+project structure in a more common way: ``Enter`` opens directory content and
``Backspace`` returns to upper level.
Shortcuts
*********
* ``<ctrl>Enter`` opens selected item with default system editor. This important
- feature is missed in many other editors. For example you may open glade file
+ feature is missing in many other editors. For example you may open glade file
as xml in Snaked (``Enter``) or show it in Glade Designer (``<ctrl>Enter``).
-* At very bottom there is project combo box, it allows switch between project
+* At very bottom there is the project choice widget, it allows switching between project
paths being searched. ``<alt>Up`` and ``<alt>Down`` keys change its value.
* ``<ctrl>p`` popups project combo box for easy selecting from large list.
-* ``<ctrl>o`` shows standard file choose dialog.
+* ``<ctrl>o`` shows standard file opener dialog.
* ``<ctrl>Delete`` deletes current project from list.
@@ -97,46 +101,46 @@ Creating new file
-----------------
Standard GTK open dialog is too frustrating and hard to use from keyboard, so
-I implemented file create panel.
+I implemented the file create panel.
.. image:: /images/create-new-file.*
-It provides folder autocomplete as you type. With ``Tab`` key you can cycle
-through proposals. ``Esc`` hides dialog, ``Enter`` opens editor with created file.
+It provides folder auto-completion as you type. With ``Tab`` key you can cycle
+through proposals. ``Esc`` hides dialog, ``Enter`` opens an editor page associated to that file name.
Sessions
--------
-Snaked provides sessions to store open editors on quit, they allow you omit
-files at all. What you have to do to enable sessions?
+Snaked provides sessions to store open editors state on quit, this allow you forget about
+files at all. The following steps are required to enable sessions:
-Run Snaked with ``-s`` (``--session``) option with session name. For example::
+Run Snaked with ``-s`` (or ``--session``) option giving a session name. For example::
snaked -s test /tmp/first_snaked_file.py
Now, after closing editor by ``<ctrl>q`` key or closing window by wm facilities
-``test`` session will be created and you can open it with simple command::
+``test`` session will be created. Thus you can open it with that simple command::
snaked -s test
-Also there is ability to select session at snaked start::
+You can also select a session on snaked startup::
snaked --select-session
-Think about sessions like some sort of workspaces which are separate you tasks.
-One session for task or project or whatever.
+Think about sessions as some sort of separate workspaces to group your files.
+One session for task or project or whatever, use it freely.
Preferences
-----------
-Preferences dialog is shown on ``<ctrl>p`` key:
+Preferences dialog is made available on ``<ctrl>p`` key press:
.. image:: /images/prefs.*
-It is alike Eclipse's quick settings. You need to type what you want to
-configure (`font`, `key`, etc.) and select wanted item.
+It is like Eclipse's quick settings. You need to type what you want to
+configure it (`font`, `key`, etc.) and select wanted item.
There are only three core configuration dialogs.
@@ -155,17 +159,17 @@ Allow one to tune editor theme, font, tabs, margin and so on.
.. image:: /images/editor-prefs.*
-Every gtksourceview language can have own settings. Also there is special
-language ``default``, it's settings spread over all langs. For example you can
-change style theme for ``default`` language and editors for other langs will be
-use it automatically.
+Every gtksourceview language can have its own settings. Also there is a special
+language: ``default``, its settings are spread over all langs. For example you can
+change style theme for ``default`` language and all editors will
+inherit this setting by default.
Plugins
*******
Simple list with available extensions. Check to enable, uncheck to disable,
-nothing more. If plugin will provide it's own configuration dialog it will
+nothing more. If a plugin provide it's own configuration dialog it will
appear in preferences.
.. image:: /images/plugins.*
@@ -180,7 +184,7 @@ least now).
* ``Tab`` / ``<shift>Tab`` -- (de)indents current line or selection.
* ``<ctrl>Space`` -- pop up completion dialog if any completions providers
- was associated with editor. There is only python provider now.
+ is associated with editor. Currently the only available provider works for python.
* ``<ctrl>c`` / ``<ctrl>v`` / ``<ctrl>x`` -- standard copy/paste/cut editor
shortcuts. Also there are common ``<ctrl>Insert`` / ``<shift>Insert`` /
@@ -188,7 +192,7 @@ least now).
* ``<ctrl>z`` / ``<ctrl>y`` -- undo/redo
-* ``<alt>Up`` / ``<alt>Down`` -- moves selection up or down. Very useful
+* ``<alt>Up`` / ``<alt>Down`` -- moves selection content up or down. Very useful
feature, especially with smart select.
@@ -198,15 +202,14 @@ Spot navigation
Snaked tries to remember important editing places and allows one to
navigate between such spots.
-Behavior is not fine tuned yet, but spot navigation satisfy my needs in
-bookmarks plugin.
+Behavior is not fine tuned yet, but spot navigation satisfy my bookmarking requirements.
How does it work?
*****************
If you move cursor to big distance (PageUp/Down, buffer start/end, switch tab,
-goto line, goto definition or moving to spot) spot is placed. Also you can place
-spot manually by ``<alt>T``. Spots are orginized as fixed length stack.
+goto line, goto definition or moving to spot) a spot is placed. You can also place
+some spot manually by pressing ``<alt>T``. Spots are organized in a fixed length stack.
Shortcuts
*********
@@ -216,7 +219,5 @@ Shortcuts
* ``<ctrl><alt>Left/Right`` moves to previous/next spot in stack.
-* ``<alt>T`` adds current cursor position as spot at top of stack.
-
-
+* ``<alt>T`` adds a spot with current cursor position on top of stack.
Please sign in to comment.
Something went wrong with that request. Please try again.