Updated documentation, readme, contribution guide

Author: Pan

.github/CONTRIBUTING.rst

@@ -31,8 +31,7 @@ When a pull request is ready to be merged, the source branch containing your cha
 Ground Rules
 ============
 
-Please keep in mind the `Code of Conduct <https://github.com/InfluxGraph/ssh2-python/blob/master/.github/code_of_conduct.md>`_ 
-when making contributions.
+Please keep in mind the `Code of Conduct <https://github.com/ParallelSSH/ssh2-python/blob/master/.github/code_of_conduct.md>`_ when making contributions.
 
 Responsibilities
 
@@ -82,10 +81,7 @@ A) If the error is from a Python traceback, include it in the bug report.
 
 B) We also need to know what platform you're running (Windows, macOS, Linux,
    docker container, etc.), the version of your Python interpreter, and the 
-   version of the library at the time of the error.
-
-C) If at all possible, steps to reproduce including sample InfluxDB data are 
-   the best way to help fixing the issue as quickly as possible.
+   versions of the library and ``libssh2`` at the time of the error.
 
 There is also an issue template to help with creating issues.
 
@@ -281,7 +277,8 @@ to be enabled on that repository.
 Building the documentation
 --------------------------
 
-Documentation is based on Sphinx, which needs to be installed to build it.
+Documentation is based on Sphinx, which is installed by development requirements per instructions
+at `Running the unit test suite`_.
 
 In root directory of repository:
 
@@ -292,7 +289,7 @@ In root directory of repository:
 
 After building succeeds the documentation is available at ``doc/_build/html``.
 
-The documentation is not currently uploaded due to issues building the native code extensions on `readthedocs`.
+The documentation is automatically uploaded to `ReadTheDocs <http://ssh2-python.readthedocs.org/en/latest/>`_ for master branch and tagged builds.
 
 .. _contributing-verify:
 

README.rst

@@ -25,20 +25,24 @@ Super fast SSH2 protocol library. ``ssh2-python`` provides Python bindings for `
 Installation
 ______________
 
-
-System packages are available on the `latest releases 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.
-
-Binary wheel packages are also provided for Linux, OSX and Windows, all Python versions, with ``libssh2`` and its required libraries included. 
+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**.
 
+``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.
+
+
 API Feature Set
 ________________
 
@@ -49,6 +53,21 @@ Complete example scripts for various operations can be found in the `examples di
 
 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
+----------------
+
+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 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
+* Provide access to ``libssh2`` error code definitions
+
 
 Quick Start
 _____________
@@ -232,22 +251,6 @@ ________________________________________
 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 reading from SFTP file handles
-* Expose errors as Python exceptions where possible
-* Provide access to ``libssh2`` error code definitions
-
-
 Comparison with other Python SSH libraries
 -------------------------------------------
 

doc/Changelog.rst

@@ -0,0 +1 @@
+../Changelog.rst

doc/index.rst

@@ -9,14 +9,22 @@ ssh2-python Documentation
 Super fast SSH2 protocol library. ``ssh2-python`` provides Python bindings for `libssh2`_.
 
 .. image:: https://img.shields.io/badge/License-LGPL%20v2-blue.svg
-  :target: https://pypi.python.org/pypi/ssh2-python
-  :alt: License
+   :target: https://pypi.python.org/pypi/ssh2-python
+   :alt: License
 .. image:: https://img.shields.io/pypi/v/ssh2-python.svg
-  :target: https://pypi.python.org/pypi/ssh2-python
-  :alt: Latest Version
+   :target: https://pypi.python.org/pypi/ssh2-python
+   :alt: Latest Version
 .. image:: https://travis-ci.org/ParallelSSH/ssh2-python.svg?branch=master
    :target: https://travis-ci.org/ParallelSSH/ssh2-python
-
+.. image:: https://ci.appveyor.com/api/projects/status/github/parallelssh/ssh2-python?svg=true&branch=master
+   :target: https://ci.appveyor.com/project/pkittenis/ssh2-python
+.. image:: https://img.shields.io/pypi/wheel/ssh2-python.svg
+   :target: https://pypi.python.org/pypi/ssh2-python
+.. image:: https://img.shields.io/pypi/pyversions/ssh2-python.svg
+   :target: https://pypi.python.org/pypi/ssh2-python
+.. image:: https://readthedocs.org/projects/ssh2-python/badge/?version=latest
+  :target: http://ssh2-python.readthedocs.org/en/latest/
+  :alt: Latest documentation
 
 .. toctree::
    :maxdepth: 2
@@ -25,7 +33,7 @@ Super fast SSH2 protocol library. ``ssh2-python`` provides Python bindings for `
    introduction
    installation
    api
-
+   Changelog
 
 Indices and tables
 ==================

doc/installation.rst

@@ -1,6 +1,27 @@
 Installation
 *************
 
+Pip Binary Packages
+====================
+
+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**.
+
+``pip`` may need to be updated to be able to install binary wheel packages.
+
+.. code-block:: shell
+
+   pip install -U pip
+
+   pip install ssh2-python
+
+.. note::
+
+   Latest version of OpenSSL is included in Linux and OSX binary wheel packages. On Windows, the native WinCNG back-end is used instead.
+
+   To control which version of OpenSSL is used for the installation either use system packages which use system libraries, the conda package, or install from source.
+
 System Binary Packages
 =======================
 
@@ -10,29 +31,46 @@ To use, download and install via the system's package manager, for example for C
 
 .. code-block:: shell
 
-   yum install -y python-ssh2-python-0.4.0-1.el7.x86_64.rpm
+   yum install -y python-ssh2-python-0.6.0-1.el7.x86_64.rpm
+
+Conda package
+===============
+
+A `conda <https://conda.io/miniconda.html>`_ package is available in the `conda-forge` channel.
+
+To install, run the following.
+
+.. code-block:: shell
+
+   conda install -c conda-forge ssh2-python
 
 Installation from Source
 ==========================
 
 To install from source, ``libssh2`` and Python development headers are required.
 
+Clone the repository, install dependencies and run install in a new virtualenv from the repository's root directory.
+
 Ubuntu
 --------
 
 .. code-block:: shell
 
-   apt-get install libssh2-1-dev python-dev
-   pip install ssh2-python
+   sudo apt-get install libssh2-1-dev python-dev
+   virtualenv my_env
+   source my_env/bin/activate
+   python setup.py install
 
 
 RedHat
 -------
 
 .. code-block:: shell
 
-   yum install libssh2-devel python-devel
-   pip install ssh2-python
+   sudo yum install libssh2-devel python-devel
+   virtualenv my_env
+   source my_env/bin/activate
+   python setup.py install
 
 
 Testing Installation