Merge branch 'docs/install-guide' into devel

PR #145

This change adds info on how to install ansible-pylibssh
using pip and how to build some dists locally.

docs/changelog-fragments/145.doc.rst

@@ -0,0 +1,2 @@
+Added the initial installation guide to docs
+-- by :user:`ganeshrn` and :user:`webknjaz`

docs/conf.py

@@ -149,6 +149,7 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'cython': ('https://cython.readthedocs.io/en/latest', None),
+    'packaging': ('https://packaging.python.org', None),
     'pip': ('https://pip.pypa.io/en/latest', None),
     'python': ('https://docs.python.org/3', None),
     'python2': ('https://docs.python.org/2', None),

docs/contributing/testing_guide.rst

@@ -61,6 +61,11 @@ your machine.
 .. _tox v3.8.0:
    https://tox.readthedocs.io/en/latest/changelog.html#v3-8-0-2019-03-27
 
+.. seealso::
+
+   :ref:`Installing |project|`
+       Installation from source
+
 Getting the source code
 =======================
 
@@ -124,7 +129,7 @@ Additionally, there's a separate workflow that runs linting\
     [dir:pylibssh] $ python -m tox -e lint  # pre-commit.com tool
 
 Continuous delivery
-^^^^^^^^^^^^^^^^^^^
+===================
 
 Besides testing and linting, |project| also has `GitHub
 Actions workflows CI/CD`_ set up to publish those same

docs/index.rst

@@ -16,6 +16,7 @@ Welcome to |project|'s documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   installation_guide
    user_guide
 
 .. toctree::

docs/installation_guide.rst

@@ -0,0 +1,131 @@
+********************
+Installing |project|
+********************
+
+This page describes how to install |project| using
+:std:doc:`pip:index`. Consult with :std:doc:`pip docs
+<pip:installing>` if you are not sure whether you have it
+set up.
+
+.. contents::
+  :local:
+
+Pre-compiled binary distributions
+=================================
+
+|project| contains :std:doc:`Cython <cython:index>`-based
+:std:term:`CPython C-extension modules <python:extension
+module>`. Unlike :std:term:`pure-Python modules
+<python:module>`, these must be pre-compiled
+before consumption.
+
+We publish :std:ref:`platform-specific wheels <platform
+wheels>` to PyPI. They are built against different arch,
+CPython and OS versions so in 99% of cases, you may
+seamlessly install |project| not needing any external
+dependencies on your system.
+
+It should be enough for you to just have Python 2.7 or
+3.5+ and a recent :std:doc:`pip <pip:index>` installed.
+
+.. attention::
+
+    Please make sure you have the latest version of
+    :std:doc:`pip <pip:index>` before installing |project|.
+
+    If you have a version of :std:doc:`pip <pip:index>`
+    older than 8.1, it'll be unable to pick up OS-specific
+    Python package distributions from PyPI and will try to
+    fall back to building it from source which would require
+    more extra dependencies to succeed.
+    You can upgrade by following :std:ref:`pip's upgrade
+    instructions <pip:upgrading pip>`.
+
+To install |project|, just run:
+
+.. parsed-literal::
+
+    $ pip install --user |project|
+
+.. tip::
+
+    Avoid running :std:doc:`pip <pip:index>` with
+    :command:`sudo` as this will make global changes to the
+    system. Since :std:doc:`pip <pip:index>` does not
+    coordinate with system package managers, it could make
+    changes to your system that leaves it in an inconsistent
+    or non-functioning state. This is particularly true for
+    macOS. Installing with :std:ref:`\-\\\\-user
+    <pip:install_--user>` is recommended unless you
+    understand fully the implications of modifying global
+    files on the system.
+
+Installing |project| from source distribution (PyPI)
+====================================================
+
+Installing |project| from source is a bit more complicated.
+First, pylibssh requires libssh to be compiled against, in
+particular, version 0.9.0 or newer. Please refer to `libssh
+Downloads page <https://www.libssh.org/get-it/>`__ for more
+information about installing it. Make sure that you have the
+development headers too.
+
+Another essential build dependency is GCC. You may already
+have it installed but if not, consult with your OS docs.
+
+Once you have the build prerequisites, the following command
+should download the tarball, build it and then install into
+your current env:
+
+.. parsed-literal::
+
+    $ pip install \\
+        --user \\
+        --no-binary |project| \\
+        |project|
+
+Building |project| dists from the ``devel`` branch in Git
+=========================================================
+
+Since our build processes are tox_-centric, let's
+install it first:
+
+.. code-block:: shell-session
+
+    $ python -m pip install 'tox >= 3.19.0' --user
+
+.. _tox: https://tox.readthedocs.io
+
+Now, let's grab the source of |project|:
+
+.. code-block:: shell-session
+
+    $ git clone https://github.com/ansible/pylibssh.git ~/src/github/ansible/pylibssh
+    $ # or, if you use SSH:
+    $ git clone [email protected]:ansible/pylibssh.git ~/src/github/ansible/pylibssh
+    $ cd ~/src/github/ansible/pylibssh
+    [dir:pylibssh] $
+
+Finally, you can build the dists for the current env using:
+
+.. code-block:: shell-session
+
+    [dir:pylibssh] $ tox -e build-dists
+
+If you want to generate the whole matrix of ``manylinux``-\
+compatible wheels, use:
+
+.. code-block:: shell-session
+
+    [dir:pylibssh] $ tox -e build-dists-manylinux  # with Docker
+
+    [dir:pylibssh] $ # or with Podman
+    [dir:pylibssh] $ DOCKER_EXECUTABLE=podman tox -e build-dists-manylinux
+
+.. seealso::
+
+   :ref:`Getting Started with |project|`
+       Examples of getting started
+
+   :ref:`Continuous delivery`
+       Using nightly builds to test your project against

docs/user_guide.rst

@@ -2,6 +2,9 @@
 Getting Started with |project|
 ******************************
 
+Now that you have read the :ref:`installation guide <Installing |project|>` and
+installed |project| on a your system.
+
 .. contents::
    :local: