Updated readme

Author: Pan

README.rst

@@ -10,46 +10,156 @@ Super fast SSH2 protocol library. ``ssh2-python`` provides Python bindings for `
   :target: https://pypi.python.org/pypi/ssh2-python
   :alt: Latest Version
 
-Features
----------
 
-Majority of the `libssh2`_ API has been implemented as Python native code extensions. ``ssh2-python`` is a thin wrapper of ``libssh2`` - ``libssh2`` code examples can be ported straight over to Python with only minimal changes.
+Installation
+______________
 
-*Library is usable for testing purposes and at the moment available as source code only. API, module names and documentation not yet finalised. Contributions welcome.*
+Install ``libssh2`` and Python header files.
 
-SSH Functionality provided
-++++++++++++++++++++++++++++
+Ubuntu
+----------
 
-* SSH channel operations (exec,shell,subsystem)
-* SSH agent
-* Public key authentication and management
-* SFTP
-* SCP
-* SSH port forwarding and tunnelling
-* Non-blocking mode
-* Listener for port forwarding
+.. code-block:: shell
 
-And more, as per `libssh2`_ functionality.
+   apt-get install libssh2-1-dev python-dev
+   pip install ssh2-python
 
 
-Native Code Extension Features
-+++++++++++++++++++++++++++++++
+RedHat
+-------
+   
+.. code-block:: shell
 
-The library uses `Cython`_ based native code extensions as wrappers to ``libssh2``.
+   yum install libssh2-devel python-dev
+   pip install ssh2-python
 
-Extension features:
 
-* Thread safe - GIL is released as much as possible
-* Very low overhead
-* Super fast as a consequence of the excellent C library it uses and that it uses native code prodigiously
-* Object oriented - memory freed automatically and safely as objects expire
-* Use Python semantics where applicable, such as iterator support for SFTP file handles
-* Expose errors as Python exceptions where possible
-* Provide access to ``libssh2`` error code definitions
+Feature Set
+_____________
+
+Majority of the `libssh2`_ API has been implemented. ``ssh2-python`` is a thin wrapper of ``libssh2`` - its code examples can be ported straight over to Python with only minimal changes.
+
+Some parts are yet to be implemented though majority of the API is complete. Note current restriction on byte strings in examples section.
+
+*Library is at the moment available as source code only. Binary releases to follow.*
+
+
+Examples
+___________
+
+Currently all string arguments are assumed to be byte strings - Python 3 users should use ``b'<string>'``.
+
+See `Complete Example`_ for a complete example including socket connect.
+
+
+Authentication Methods
+-------------------------
+
+
+Connect and get available authentication methods.
+
+
+.. code-block:: python
+
+   from __future__ import print_function
+
+   from ssh2.session import Session
+
+   sock = <create and connect socket>
+
+   session = Session()
+   session.handshake(sock)
+   print(session.userauth_list())
+
+
+.. code-block:: python
+
+   ['publickey', 'password', 'keyboard-interactive']
+
+
+Agent Authentication
+------------------------
+
+
+.. code-block:: python
+
+   session.agent_auth(user)
+
+
+Command Execution
+------------------------
+
+
+.. code-block:: python
+
+   channel = session.open_session()
+   channel.execute('echo Hello')
+
+
+Reading Output
+---------------
+
+.. code-block:: python
+
+   size, data = channel.read()
+   while(size > 0):
+       print(data)
+       size, data = channel.read()
+
+.. code-block:: python
+
+   Hello
+
+
+Exit Code
+--------------
+
+.. code-block:: python
+
+   print("Exit status: {}".format(channel.get_exit_status()))
+
+
+.. code-block:: python
 
+   Exit status: 0
+
+
+Public Key Authentication
+----------------------------
+
+.. code-block:: python
+
+   session.userauth_publickey_fromfile(
+       username, 'my_pkey.pub', 'my_pkey', '')
+
+
+Where ``''`` can be a passphrase.
+
+
+Password Authentication
+----------------------------
+
+
+.. code-block:: python
+
+   session.userauth_password(
+       username, '<my password>')
+
+SFTP Read
+-----------
+
+.. code-block:: python
 
-Example
---------
+   sftp = session.sftp_init()
+   fh = sftp.open(<file path>, 0, 0)
+   with open(<file to write>, 'wb') as local_fh:
+       for data in fh:
+           local_fh.write(data)
+   fh.close()
+
+
+Complete Example
+__________________
 
 A simple usage example looks very similar to ``libssh2`` `usage examples <https://www.libssh2.org/examples/>`_.
 
@@ -93,6 +203,38 @@ Clients using this library can be much simpler to use than interfacing with the
    Exit status: 2
 
 
+SSH Functionality currently provided
+_____________________________________
+
+
+* SSH channel operations (exec,shell,subsystem)
+* SSH agent
+* Public key authentication and management
+* SFTP
+* SCP
+* SSH port forwarding and tunnelling
+* Non-blocking mode
+* Listener for port forwarding
+
+And more, as per `libssh2`_ functionality.
+
+
+Native Code Extension Features
+_______________________________
+
+The library uses `Cython`_ based native code extensions as wrappers to ``libssh2``.
+
+Extension features:
+
+* Thread safe - GIL is released as much as possible
+* Very low overhead
+* Super fast as a consequence of the excellent C library it uses and that it uses native code prodigiously
+* Object oriented - memory freed automatically and safely as objects expire
+* Use Python semantics where applicable, such as iterator support for SFTP file handles
+* Expose errors as Python exceptions where possible
+* Provide access to ``libssh2`` error code definitions
+
+
 Comparison with other Python SSH2 libraries
 ---------------------------------------------