Readme and documentation update.

Author: Pan

README.rst

@@ -25,34 +25,29 @@ Super fast SSH2 protocol library. ``ssh2-python`` provides Python bindings for `
 Installation
 ______________
 
-Binary wheel packages are provided for Linux, OSX and Windows, all Python versions, with ``libssh2`` and its required libraries included.
-
-Wheel packages have **no dependencies**.
+Binary wheel packages are provided for Linux, OSX and Windows, all Python versions. Wheel packages have **no dependencies**.
 
 ``pip`` may need to be updated to be able to install binary wheel packages - ``pip install -U pip``.
 
 .. code-block:: shell
 
    pip install ssh2-python
 
-
-System packages are also available on the `latest release page <https://github.com/ParallelSSH/ssh2-python/releases/latest>`_ built on Centos/RedHat 6/7, Ubuntu 14.04/16.04, Debian 7/8 and Fedora 22/23/24.
-
-System packages have *no dependencies* other than the ``libssh2`` system library.
-
 `Conda <https://conda.io/miniconda.html>`_ is another installation option - see `documentation <http://ssh2-python.readthedocs.org/en/latest/>`_ for more detailed instructions.
 
+For creating native system packages for Centos/RedHat, Ubuntu, Debian and Fedora, see `instructions in the documentation <http://ssh2-python.readthedocs.io/en/latest/installation.html#system-binary-packages>`_.
+
 
 API Feature Set
 ________________
 
-
-At this time all of the `libssh2`_ API has been implemented up to version ``1.8.0``.
+At this time all of the `libssh2`_ API has been implemented up to version ``1.8.2``.
 
 Complete example scripts for various operations can be found in the `examples directory`_.
 
 In addition, as ``ssh2-python`` is a thin wrapper of ``libssh2`` with Python semantics, its code examples can be ported straight over to Python with only minimal changes.
 
+
 Library Features
 ----------------
 
@@ -65,16 +60,16 @@ Extension features:
 * Super fast as a consequence of the excellent C library it uses and prodigious use of native code
 * Object oriented - memory freed automatically and safely as objects are garbage collected by Python
 * Use Python semantics where applicable, such as context manager and iterator support for opening and reading from SFTP file handles
-* Expose errors as Python exceptions where possible
+* Raise errors as Python exceptions
 * Provide access to ``libssh2`` error code definitions
 
 
 Quick Start
 _____________
 
-Both byte and unicode strings are accepted as arguments and encoded appropriately. To change default encoding, ``utf-8``, change the value of ``ssh2.utils.ENCODING``. Channel output is always byte strings.
+Both byte and unicode strings are accepted as arguments and encoded appropriately. To change default encoding, ``utf-8``, change the value of ``ssh2.utils.ENCODING``. Output is always in byte strings.
 
-See `Complete Example`_ for a complete example including socket connect.
+See `Complete Example`_ for an example including socket connect.
 
 Please use either the issue tracker for reporting issues with code or the `mail group`_ for discussion and questions.
 
@@ -196,7 +191,7 @@ A simple usage example looks very similar to ``libssh2`` `usage examples <https:
 
 See `examples directory <https://github.com/ParallelSSH/ssh2-python/tree/master/examples>`_ for more complete example scripts.
 
-As mentioned, ``ssh2-python`` is intentially a thin wrapper over ``libssh2`` and directly maps most of its API.
+As mentioned, ``ssh2-python`` is intentionally a thin wrapper over ``libssh2`` and directly maps most of its API.
 
 Clients using this library can be much simpler to use than interfacing with the ``libssh2`` API directly.
 

doc/installation.rst

@@ -35,9 +35,9 @@ To use the built packages, install via the system's package manager, for example
 
 .. note::
 
-  System packages use the system provided ``libssh2`` which may need to be updated to be compatible with ``ssh2-python``. ``libssh2`` ersions ``>= 1.6.0`` are compatible.
+  System packages use the system provided ``libssh2`` which may need to be updated to be compatible with ``ssh2-python``. ``libssh2`` versions ``>= 1.6.0`` are compatible.
 
-  To built an ``ssh2-python`` that is compatible with versions lower than ``1.6.0``, run the build with the ``EMBEDDED_LIB=0`` environment variable set. This will disable features that require ``libssh2`` >= ``1.6.0``.
+  To build an ``ssh2-python`` that is compatible with versions lower than ``1.6.0``, run the build with the ``EMBEDDED_LIB=0`` environment variable set. This will disable features that require ``libssh2`` >= ``1.6.0``.
 
 Conda package
 ===============
@@ -55,10 +55,42 @@ Installation from Source
 
 To install from source, ``libssh2`` and Python development headers are required.
 
+Custom build
+-------------
+
+For best compatibility, it is recommended to use the ``libssh2`` submodule included in ``ssh2-python`` repository to build with.
+
+.. code-block:: shell
+
+   git clone --recurse-submodules [email protected]:ParallelSSH/ssh2-python.git
+   sudo ./ci/install-ssh2.sh
+   virtualenv my_env
+   source my_env/bin/activate
+   python setup.py install
+
+The ``sudo ./ci/install-ssh2.sh`` line will install a version of ``libssh2`` under ``/usr/local`` that is the same version used to build binary wheels with and is ensured to be compatible.
+
+If there are multiple development headers and/or libraries for ``libssh2`` on the system, the following can be used to set the include path, runtime and build library directories:
+
+.. code-block:: shell
+
+   git clone --recurse-submodules [email protected]:ParallelSSH/ssh2-python.git
+   sudo ./ci/install-ssh2.sh
+   source my_env/bin/activate
+   python setup.py build_ext -I /usr/local/include -R /usr/local/lib -L /usr/local/lib
+   python setup.py install
+
+System library build
+---------------------
+
+Building against system provided ``libssh2`` is another option which may be preferred. 
+
+If the ``libssh2`` version provided by the system is not compatible, run the build with the ``EMBEDDED_LIB=0`` environment variable set. This will disable features that require ``libssh2`` >= ``1.6.0``.
+
 Clone the repository, install dependencies and run install in a new virtualenv from the repository's root directory.
 
 Ubuntu
---------
+_______
 
 .. code-block:: shell
 
@@ -69,7 +101,7 @@ Ubuntu
 
 
 RedHat
--------
+_______
 
 .. code-block:: shell