Update general information and setup instructions

Refs grnet/kamaki#49

docs/conf.py

@@ -123,13 +123,13 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Kamaki'
-copyright = u'2013, GRNET'
+copyright = u'2014, GRNET'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.12'
+version = '0.13'
 # The full version, including alpha/beta/rc tags.
 
 try:

docs/installation.rst

@@ -16,17 +16,15 @@ have it up and running in all platforms running Python 2.6 or 2.7.
 Linux and Unix-like environments
 --------------------------------
 
-Debian:
-^^^^^^^
+Debian
+^^^^^^
 
-The following steps describe a command-line approach, but any graphic package manager can be used instead.
+For Debian 7.0 (wheezy):
 
 * As root, append the following to */etc/apt/sources.list* ::
 
     deb http://apt.dev.grnet.gr wheezy/
 
-.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze"
-
 * Make sure the GPG public key for the Synnefo repository is added:
 
     .. code-block:: console
@@ -35,99 +33,108 @@ The following steps describe a command-line approach, but any graphic package ma
 
     otherwise *apt-get update* will produce GPG warnings.
 
-* Update the Debian sources:
+* Update and install:
 
     .. code-block:: console
 
         $ sudo apt-get update
+        $ sudo apt-get install kamaki
 
-* Install kamaki:
+Terminal colors (optional but recommended)
+""""""""""""""""""""""""""""""""""""""""""
 
-    .. code-block:: console
+The "python-ansicolors" package enables colorful terminal outputs.
 
-        $ sudo apt-get install kamaki
+E.g., in Debian:
 
-Ubuntu
-^^^^^^
-
-The following steps describe a command-line approach, but any graphic package
-manager can be used instead.
+.. code-block:: console
 
-* Let ppa take care of the repository configuration:
+    $ sudo apt-get install python-ansicolors
 
-    .. code-block:: console
+After the installation, tell kamaki to use the feature
 
-        $ sudo apt-get install python-software-properties
-        $ sudo add-apt-repository ppa:grnet/synnefo
+.. code-block:: console
 
-* Update the Debian sources:
+    $ kamaki config set colors on
 
-    .. code-block:: console
+Unit tests (developers)
+"""""""""""""""""""""""
 
-        $ sudo apt-get update
+Install the "python-mock" package to make unit tests work (developers only).
 
-* Install kamaki:
+.. code-block:: console
 
-    .. code-block:: console
+    $ sudo apt-get install python-mock
 
-        $ sudo apt-get install kamaki
+Ubuntu
+^^^^^^
 
-Install ansicolors (optional but recommended)
-"""""""""""""""""""""""""""""""""""""""""""""
+For Ubuntu 12.04 LTS, 12.10 and 13.04:
 
 .. code-block:: console
 
-    $ sudo apt-get install python-ansicolors
+    $ sudo apt-get install python-software-properties
+    $ sudo add-apt-repository ppa:grnet/synnefo
+    $ sudo apt-get update
+    $ sudo apt-get install kamaki
 
+Fedora
+^^^^^^
 
-.. _installing-from-pypi-ref:
+For Fedora 17:
 
-Installing from pypi
-^^^^^^^^^^^^^^^^^^^^
+.. code-block:: console
 
-Requirements
-""""""""""""
+    $ cd /etc/yum.repos.d
+    $ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/Fedora_17/home:GRNET:synnefo.repo
+    $ yum install kamaki
 
-Essential:
+CentOS
+^^^^^^
 
- * Python 2.6 or 2.7 [http://www.python.org]
- * Python setuptools [http://pypi.python.org/pypi/setuptools]
+For CentOS 6:
 
-Optional:
+.. code-block:: console
 
- * VirtualEnv (python-virtualenv) [http://www.virtualenv.org]
+    $ cd /etc/yum.repos.d
+    $ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/CentOS_CentOS-6/home:GRNET:synnefo.repo
+    $ yum install kamaki
 
-Setup a virtual enviroment (optional)
-"""""""""""""""""""""""""""""""""""""
+OpenSUSE
+^^^^^^^^
 
-Use virtualenv to setup kamaki and Synnefo services in a sandbox environment.
+For OpenSUSE 12.3:
 
 .. code-block:: console
 
-    $ virtualenv kamaki-env
-    $ source kamaki-env/bin/activate
+    $ zypper ar -f http://download.opensuse.org/repositories/home:/GRNET:/synnefo/openSUSE_12.3/home:GRNET:synnefo.repo
+    $ zypper in kamaki
 
-A more detailed example of using virtual env can be found at the 
-`snf-image-creator setup guide <http://www.synnefo.org/docs/snf-image-creator/latest/install.html#python-virtual-environment>`_
 
-Install kamaki
-""""""""""""""
+.. _installing-from-pypi-ref:
+
+Installing from pypi
+--------------------
+
+Requirements:
+
+ * Python 2.7 [http://www.python.org]
+ * Python setuptools [http://pypi.python.org/pypi/setuptools]
+
+Installation:
 
 .. code-block:: console
 
     $ pip install kamaki
 
-Install ansicolors
-""""""""""""""""""
-
-The **ansicolors** package is not required for running kamaki, but it is
-recommended as a user experience improvement. In specific, ansicolors
-adds colors to kamaki responses.
+Optional packages:
+The ansicolors package enables terminal output coloring. The mock package
+allows unit testing while hacking the code.
 
 .. code-block:: console
 
     $ pip install ansicolors
-
+    $ pip install mock
 
 Mac OS X
 --------
@@ -141,29 +148,22 @@ Windows
 Kamaki can be installed on Windows by following the pypi method. Installing the
 requirements is a bit different than in other systems. 
 
-The full process is detailed in the following:
-
-Requirements
-^^^^^^^^^^^^
+**Requirements**
 
 * Python 2.7 (`Official versions <http://www.python.org/download>`_)
 
 * Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
 
-Users who have already set up python and setuptools (e.g., for
-another project) may skip Python and / or setuptools installation.
-
 Install Python
 ^^^^^^^^^^^^^^
 
-Download and run the Windows installer from
-`here <http://www.python.org/download>`_
+.. note:: Skip this step if python 2.7 is already installed
 
-Users should pick the installer that fits their windows version and machine
-architecture.
+Download and run the Windows installer from
+`the download page <http://www.python.org/download>`_
+pick the one that fits your windows version and architecture.
 
-Add Python to windows path
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Add Python to windows path**
 
 The following will allow users to run Python and Python scripts from command
 line.
@@ -181,20 +181,18 @@ line.
 .. warning:: In case of a different version, C:\\Python27 should be replaced
     with the actual python path in the system
 
-Install setuptools
+Install Setuptools
 ^^^^^^^^^^^^^^^^^^
 
-According to the corresponding
-`python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools
-installer doesn't currently work on 64bit machines.
+.. note:: Skip this step if setuptools are already installed
 
-* Users with 32-bit platforms should download and run the graphic
-    installer
+See `here <http://pypi.python.org/pypi/setuptools>`_ for installation
+instructions.
 
-* Users with 64-bit platforms should download the
-    `ez_setup.py <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_
-    script and install it from a command shell. In the following example, the
-    script was downloaded at C:\\Downloads::
+.. note:: Users with 64-bit platforms should download the
+    `ez_setup.py <https://bootstrap.pypa.io/ez_setup.py>`_ script and install
+    it from a command shell. In the following example, the script was
+    downloaded at C:\\Downloads::
 
         C:\> cd Downloads
         C:\Downloads\> python ez_setup.py

docs/overview.rst

@@ -49,8 +49,8 @@ command-line tool for managing a local or remote Synnefo deployment.
 
 * by third-party `Synnefo` deployers for testing and debugging their setup
 
-* as an API library for other components in the Synnefo universe ((`burnin`,
-    `image-creator`) or external applications
+* as an API library for Synnefo-related components (`burnin`, `image-creator`)
+    or external applications
 
 Community & Support
 -------------------

docs/usage.rst

@@ -3,7 +3,7 @@ Usage
 
 Kamaki features commands of the form::
 
-  [kamaki] <object> <action> [identifier(s)] <non-positional arguments>
+  kamaki <object> <action> [identifier(s)] <non-positional arguments>
   e.g., 
   kamaki user info --username=user@example.com
 
@@ -24,14 +24,12 @@ interactive shell:
   [kamaki]: user info
   ... RESULTS ...
 
-In the later, the term "one-command" will be user to refer to running kamaki
-commands from host shell, while the term "shell" will refer to the kamaki's own
-interactive shell
+In the following, the term "one-command" refer to running kamaki commands from
+host shell, while the term "shell" will refer to the interactive shell.
 
 .. note:: This section refers to the kamaki CLI. Developers and people who write
   scripts, should rather use the the
-  `Clients lib <developers/code.html#the-clients-api>`_ instead of the kamaki
-  CLI.
+  `Clients library <developers/code.html#the-clients-api>`_ instead.
 
 Quick Setup
 -----------
@@ -44,13 +42,12 @@ As rule of the thump, it is enough to set a cloud authentication URL and TOKEN:
 .. code-block:: console
     :emphasize-lines: 1
 
-    Example 1.1: Set authentication URL, user token for cloud alias "default"
+    Example 1.1: Set authentication URL, user token for cloud alias CLOUD_NAME
 
-    $ kamaki config set cloud.default.url <authentication URL>
-    $ kamaki config set cloud.default.token myt0k3n==
+    $ kamaki config set cloud.CLOUD_NAME.url <authentication URL>
+    $ kamaki config set cloud.CLOUD_NAME.token myt0k3n==
 
-.. note:: The term *default* can be replaced by any arbitary term chosen by
-    the user.
+.. note:: The term CLOUD_NAME is arbitrary and can be chosen by the user
 
 Shell vs one-command
 --------------------
@@ -62,10 +59,9 @@ implementation. However, there are some minor differences.
 
 In favor of interactive shell:
 
-* shorter commands (context switching)
+* shorter commands
 * tab completion for commands (if supported by host shell)
 * kamaki-specific history with ↑ or ↓ keys (if supported by host shell)
-* re-run old commands with /history
 
 In favor of one-command:
 
@@ -83,7 +79,7 @@ To use kamaki as a shell, run:
 
     $ kamaki-shell
 
-* with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
+* with any kind of '-' prefixed arguments, except '-h', '- - help', '-V',
     '- - version'.
 
 .. code-block:: console
@@ -95,16 +91,16 @@ To use kamaki as a shell, run:
 
     Example 2.2.3: Run kamaki shell so as to use a specific cloud
 
-    $ kamaki-shell --cloud=my_demo_cloud
+    $ kamaki-shell --cloud=example_cloud
 
-    Example 2.2.4: Run kamaki shell with verbosity (shows HTTP requests)
+    Example 2.2.4: Run kamaki shell with verbosity (prints HTTP communication)
 
     $ kamaki-shell -v
 
-.. note:: Valid arguments can be combined e.g., it is ok to run a shell with
-  verbosity and a specific cloud::
+.. note:: Valid arguments can be combined e.g., to run a shell with verbosity
+    and a specific cloud::
 
-    $ kamaki-shell -v --cloud=my_demo_cloud
+    $ kamaki-shell -v --cloud=example_cloud
 
 Run as one-command
 ^^^^^^^^^^^^^^^^^^
@@ -113,9 +109,6 @@ To use kamaki as an one-command tool, run:
 * with the '-h' or '--help' arguments (help for kamaki one-command)
 
 .. code-block:: console
-    :emphasize-lines: 1
-
-    Example 2.3.1: Kamaki help
 
     $kamaki -h
 
@@ -124,7 +117,7 @@ To use kamaki as an one-command tool, run:
 .. code-block:: console
     :emphasize-lines: 1
 
-    Example 2.3.2: List servers managed by user
+    Example 2.3.2: List virtual servers
 
     $ kamaki server list
 

kamaki/cli/config/__init__.py

@@ -341,7 +341,7 @@ class Config(RawConfigParser):
 
     def get_cloud(self, cloud, option):
         """
-        :param cloud: (str) cloud alias
+        :param cloud: (str) cloud name
 
         :param option: (str) option in cloud section