Improvements in documentation of installation instructions.

(Redmine issue: #4216)

doc/sphinx/_doclib/installation.rst

@@ -22,6 +22,10 @@ to your setup and preferences.
     team. That is the reason why we did not add that directly to the list of Debian
     package dependencies.
 
+For your convenience there is a section dedicated to installation of prerequisites:
+
+#. :ref:`section-installation-prerequisites`
+
 To sum it up currently you have following installation options:
 
 #. :ref:`section-installation-manual`
@@ -156,17 +160,78 @@ manually, you can use ``pip3`` and prepared Python requirements file
     (venv) $ deactivate
 
 
+.. _section-installation-prerequisites:
+
+Installation guide - Prerequisites
+--------------------------------------------------------------------------------
+
+This section is included here solely for your convenience. Please be aware, that
+official installation instructions in the official documentation is always best
+source of information. Please refer to that documentation in case you encounter
+any errors.
+
+
+.. _section-installation-prerequisites-postgresql:
+
+PostgreSQL 11
+````````````````````````````````````````````````````````````````````````````````
+
+* `Documentation <https://www.postgresql.org/docs/>`__
+* `Installation guide for Debian systems <https://www.postgresql.org/download/linux/debian/>`__
+
+.. code-block:: shell
+
+    # Run these commands as root:
+    $ echo "deb http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main" | tee /etc/apt/sources.list.d/pgdg.list
+    $ wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
+    $ aptitude update
+    $ aptitude install postgresql-11 postgresql-11-ip4r postgresql-client-11 postgresql-server-dev-11 libpq-dev pgadmin4
+
+
+.. _section-installation-prerequisites-yarn:
+
+NodeJS and Yarn
+````````````````````````````````````````````````````````````````````````````````
+
+* `Documentation <https://yarnpkg.com/en/docs>`__
+* `Installation guide for Debian systems <https://yarnpkg.com/en/docs/install#debian-stable>`__
+
+.. code-block:: shell
+
+    # Run these commands as root:
+    $ curl -sL https://deb.nodesource.com/setup_8.x | bash -
+    $ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
+    $ echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
+    $ aptitude update
+    $ aptitude install build-essential nodejs yarn
+
+
+.. _section-installation-prerequisites-grunt:
+
+Grunt
+````````````````````````````````````````````````````````````````````````````````
+
+* `Documentation <https://gruntjs.com/>`__
+* `Installation guide for Debian systems <https://gruntjs.com/getting-started>`__
+
+.. code-block:: shell
+
+    # Run these commands as root:
+    $ npm install -g grunt-cli
+
+
 .. _section-installation-manual:
 
 Installation guide - Manual installation
 --------------------------------------------------------------------------------
 
 The installation of base system is pretty straightforward, please follow these
-simple steps:
+simple steps (all commands should be executed as root):
 
 .. code-block:: shell
 
-    # Step 1: Install and configure PostgreSQL database. See official documentation or use our Ansible role.
+    # Step 1: Install and configure PostgreSQL database. See official documentation,
+    # or refer to appropriate section above.
 
     # Step 2: Download apt list file for mentat production package repository:
     $ wget -O /etc/apt/sources.list.d/mentat-production.list https://alchemist.cesnet.cz/mentat/deb/mentat-production.list
@@ -187,15 +252,21 @@ After these steps there are several post-installation tasks to be performed:
 
 .. code-block:: shell
 
+    # To be safe activate the Python virtual environment:
+    $ . /var/mentat/venv/bin/activate
+
     # Step 8: Initialize PostgreSQL database schema:
-    $ mentat-dbmngr.py --command init
+    (venv) $ mentat-dbmngr.py --command init
 
     # Step 9: Stamp both metadata end event databases with latest migration revisions:
-    $ hawat-cli db stamp head
-    $ /etc/mentat/scripts/sqldb-migrate.sh stamp head
+    (venv) $ hawat-cli db stamp head
+    (venv) $ /etc/mentat/scripts/sqldb-migrate.sh stamp head
 
     # Step 10: Precache various event search form select option dictionaries:
-    $ mentat-precache.py --allow-empty
+    (venv) $ mentat-precache.py --allow-empty
+
+    # Deactivate now unnecessary virtual environment:
+    (venv) $ deactivate
 
 The Mentat system is now successfully installed. You may try to start everything up:
 
@@ -223,7 +294,7 @@ you must provide following prerequisites on the target host system:
 
 * Python3>=3.5.3
 * pip
-* PostgreSQL 11
+* `PostgreSQL 11 <https://www.postgresql.org/>`__
 * `Yarn <https://yarnpkg.com/en/>`__
 * `Grunt <https://gruntjs.com/>`__
 
@@ -232,11 +303,14 @@ simple steps:
 
 .. code-block:: shell
 
-    # Step 1: Install and configure PostgreSQL database (please refer to the official documentation or use our Ansible role).
+    # Step 1: Install and configure PostgreSQL database. See official documentation,
+    # or refer to appropriate section above.
 
-    # Step 2: Install Yarn package manager for Node.JS (please refer to the official documentation).
+    # Step 2: Install Yarn package manager for Node.JS. See official documentation,
+    # or refer to appropriate section above.
 
-    # Step 3: Install Grunt task manager (please refer to the official documentation).
+    # Step 3: Install Grunt task manager. See official documentation, or refer to
+    # appropriate section above.
 
     # Step 4: Clone the git repository. Please note, that following command uses
     # HTTPS and you will therefore have read-only access to the repository. In