Improve installation guide

Previously the installation guide seems to target developers.
This commit makes it more generic and add some useful contents.

Change-Id: I75a996e315e3d46c41c66a22f93be70ee5807837

doc/source/install/index.rst

@@ -2,8 +2,80 @@
 Heat Dashboard installation guide
 =================================
 
-.. toctree::
+This page describes the manual installation of heat-dashboard,
-   :maxdepth: 1
+while distribution packages may provide more automated process.
 
-   installation
+.. note::
-   uninstallation
+
+   This page assumes horizon has been installed.
+   Horizon setup is beyond the scope of this page.
+
+Install Heat Dashboard with all relevant packages to your Horizon environment.
+
+.. code-block:: console
+
+    pip install heat-dashboard
+
+In most cases, heat-dashboard is installed into your python "site-packages"
+directory like ``/usr/local/lib/python2.7/site-packages``.
+We refer to the directory of heat-dashboard as ``<heat-dashboard-dir>`` below
+and it would be ``<site-packages>/heat_dashboard`` if installed via pip.
+The path varies depending on Linux distribution you use.
+
+To enable heat-dashboard plugin, you need to put horizon plugin setup files
+into horizon "enabled" directory.
+
+The plugin setup files are found in ``<heat-dashboard-dir>/enabled``.
+
+.. code-block:: console
+
+   $ cp <heat-dashboard-dir>/enabled/_[1-9]*.py \
+         /usr/share/openstack-dashboard/openstack_dashboard/local/enabled
+
+.. note::
+
+   The directory ``local/enabled`` may be different depending on your
+   environment or distribution used. The path above is one used in Ubuntu
+   horizon package.
+
+Configure the policy file for heat-dashboard in OpenStack Dashboard
+``local_settings.py``.
+
+.. code-block:: python
+
+   POLICY_FILES['orchestration'] = '<heat-dashboard-dir>/conf/heat_policy.json'
+
+.. note::
+
+   If your ``local_settings.py``  has no ``POLICY_FILES`` yet,
+   you need to define the default ``POLICY_FILES`` in
+   ``local_settings.py``. If you use the example ``local_settings.py`` file
+   from horizon, what you need is to uncomment ``POLICY_FILES`` (which contains
+   the default values).
+
+You can also add additional configurations to ``local_settings.py``.
+For more detail, see :doc:`/configuration/configuration`.
+You can also find an example file at
+``<heat-dashboard-dir>/heat_dashboard/local_settings.d``.
+
+Compile the translation message catalogs of heat-dashboard.
+
+.. code-block:: console
+
+   $ cd <heat-dashboard-dir>
+   $ python ./manage.py compilemessages
+
+Run the Django update commands.
+Note that ``compress`` is required when you enable compression.
+
+.. code-block:: console
+
+   $ cd <horizon-dir>
+   $ DJANGO_SETTINGS_MODULE=openstack_dashboard.settings python manage.py collectstatic --noinput
+   $ DJANGO_SETTINGS_MODULE=openstack_dashboard.settings python manage.py compress --force
+
+Finally, restart your web server. For example, in case of apache:
+
+.. code-block:: console
+
+   $ sudo service apache2 restart

doc/source/install/installation.rst

@@ -1,54 +0,0 @@
-============
-Installation
-============
-
-Manual Installation
--------------------
-
-Clone both Horizon and Heat Dashboard repositories::
-
-    git clone https://github.com/openstack/horizon
-    git clone https://github.com/openstack/heat-dashboard
-
-Create a virtual environment and install Horizon relevant packages::
-
-    pip install -r horizon/requirements.txt
-
-Create your ``local_settings.py`` file::
-
-    cp horizon/openstack_dashboard/local/local_settings.py.example \
-      horizon/openstack_dashboard/local/local_settings.py
-
-Open newly created ``local_settings.py`` with your text editor,
-and set some parameter to connect to your OpenStack environment:
-
-- Set ``OPENSTACK_HOST`` as hostname or IP address of your OpenStack server.
-
-- Verify that the ``OPENSTACK_KEYSTONE_URL`` and
-   ``OPENSTACK_KEYSTONE_DEFAULT_ROLE`` settings are correct for your
-   environment. (They should be correct unless you modified your
-   OpenStack server to change them.)
-
-Install Heat Dashboard with all relevant packages to your Horizon environment::
-
-    pip install -e ./heat-dashboard/
-
-Enable heat-dashboard plugin in your Horizon environment::
-
-    cp heat-dashboard/heat_dashboard/enabled/* \
-      horizon/openstack_dashboard/local/enabled
-
-    cp heat-dashboard/heat_dashboard/conf/* \
-      horizon/openstack_dashboard/conf/
-
-    cp heat-dashboard/heat_dashboard/local_settings.d/* \
-      horizon/openstack_dashboard/local/local_settings.d/
-
-
-Finally you can launch Horizon with Heat Dashboard plugin::
-
-    cd horizon
-    python manage.py runserver 0.0.0.0:8080
-
-Now you can connect to your Horizon including Heat Dashboard plugin
-from your browser with URL http://localhost:8080/.

doc/source/install/uninstallation.rst

@@ -1,14 +0,0 @@
-==============
-Uninstallation
-==============
-
-To uninstall this plugin, use ``pip uninstall heat-dashboard``
-in your Horizon's virtual environment.
-
-You also need to remove following files::
-
-_1610_project_orchestration_panel.py
-_1620_project_stacks_panel.py
-_1630_project_resource_types_panel.py
-_1640_project_template_versions_panel.py
-_1650_project_template_generator_panel.py