Merge "Add more installation instructions"

doc/source/installation.rst

@@ -3,11 +3,39 @@
 Installation
 ============
 
-*Install pip*::
+About using pip
+---------------
+
+Installing zuul-client from source or PyPI requires pip.
+
+*Install pip on Linux*::
 
   [apt-get | yum] install python-pip
 
-More information on pip here: http://www.pip-installer.org/en/latest/
+However using pip to install python packages directly on your operating system might
+interfere with your OS's package management. It is recommended to use pip within
+a virtual environment instead.
+
+*Install python virtualenv*::
+
+  [apt-get | yum | dnf] install python-virtualenv
+
+*Create a virtualenv*::
+
+  python -m venv zuul-client-venv
+
+*Activate the virtual environment*::
+
+  source zuul-client-venv/bin/activate
+
+The pip executable will be pre-installed in the virtual environment.
+
+More information on virtual environments here: https://docs.python.org/3/library/venv.html
+
+From source
+-----------
+
+Within a virtual environment or after having installed pip on your system:
 
 *Install dependencies*::
 
@@ -16,3 +44,29 @@ More information on pip here: http://www.pip-installer.org/en/latest/
 *Install zuul-client*::
 
   python setup.py install
+
+Via the Python Package Index (PyPI)
+-----------------------------------
+
+Within a virtual environment or after having installed pip on your system:
+
+*Install zuul-client*::
+
+  pip install zuul-client
+
+Via the zuul-client container
+-----------------------------
+
+A container engine such as `podman <https://podman.io/getting-started/installation>`_
+or `docker <https://docs.docker.com/get-docker/>`_ is required to use the
+zuul-client container.
+
+*Pull the container*::
+
+  [docker | podman] pull docker.io/zuul/zuul-client
+
+*Run zuul-client from the container*::
+
+  [docker | podman] run zuul/zuul-client --help
+
+Please refer to the container engine's documentation for more runtime options.