Add install guide for users and clean up README

* Add "Using Horizon" section to the docs, which describes
  how to install and configure Horizon. It is for operators
  who install Horizon from source code.
* Clean up README.rst as much of the information is out-of-date
  and most of it is covered by the developer docs.
* Minor update of page titles.

Change-Id: I09aab0d0bc47e07c8d663e7f7b5801e456434950

README.rst

@@ -8,83 +8,26 @@ from reusable components. The ``openstack_dashboard`` module is a reference
 implementation of a Django site that uses the ``horizon`` app to provide
 web-based interactions with the various OpenStack projects.
 
-For release management:
+* Release management: https://launchpad.net/horizon
-
+* Blueprints and feature specifications: https://blueprints.launchpad.net/horizon
- * https://launchpad.net/horizon
+* Issue tracking: https://bugs.launchpad.net/horizon
-
-For blueprints and feature specifications:
-
- * https://blueprints.launchpad.net/horizon
-
-For issue tracking:
-
- * https://bugs.launchpad.net/horizon
 
 
-Getting Started
+Using Horizon
-===============
+=============
 
-For local development, first create a virtualenv for the project.
+See ``doc/source/topics/install.rst`` about how to install Horizon
-In the ``tools`` directory there is a script to create one for you::
+in your OpenStack setup. It describes the example steps and
+has pointers for more detailed settings and configurations.
 
-  $ python tools/install_venv.py
+It is also available at http://docs.openstack.org/developer/horizon/topics/install.html.
 
-Alternatively, the ``run_tests.sh`` script will also install the environment
+Getting Started for Developers
-for you and then run the full test suite to verify everything is installed
+==============================
-and functioning correctly.
 
-Now that the virtualenv is created, you need to configure your local
+``doc/source/quickstart.rst`` or
-environment.  To do this, create a ``local_settings.py`` file in the
+http://docs.openstack.org/developer/horizon/quickstart.html
-``openstack_dashboard/local/`` directory.  There is a
+describes how to setup Horizon development environment and start development.
-``local_settings.py.example`` file there that may be used as a template.
-
-If all is well you should able to run the development server locally::
-
-  $ tools/with_venv.sh ./manage.py runserver
-
-or, as a shortcut::
-
-  $ ./run_tests.sh --runserver
-
-
-Setting Up OpenStack
-====================
-
-The recommended tool for installing and configuring the core OpenStack
-components is `Devstack`_. Refer to their documentation for getting
-Nova, Keystone, Glance, etc. up and running.
-
-.. _Devstack: http://devstack.org/
-
-.. note::
-
-    The minimum required set of OpenStack services running includes the
-    following:
-
-    * Nova (compute, api, scheduler, network, *and* volume services)
-    * Glance
-    * Keystone
-
-    Optional support is provided for Swift.
-
-
-Development
-===========
-
-For development, start with the getting started instructions above.
-Once you have a working virtualenv and all the necessary packages, read on.
-
-If dependencies are added to either ``horizon`` or ``openstack_dashboard``,
-they should be added to ``requirements.txt``.
-
-The ``run_tests.sh`` script invokes tests and analyses on both of these
-components in its process, and it is what Jenkins uses to verify the
-stability of the project. If run before an environment is set up, it will
-ask if you wish to install one.
-
-To run the unit tests::
-
-    $ ./run_tests.sh
 
 Building Contributor Documentation
 ==================================

doc/source/index.rst

@@ -30,17 +30,15 @@ For a more in-depth look at Horizon and its architecture, see the
 
 To learn what you need to know to get going, see the :doc:`quickstart`.
 
-Getting Started With Horizon
+Using Horizon
-============================
+=============
 
 How to use Horizon in your own projects.
 
 .. toctree::
    :maxdepth: 1
 
-   intro
+   topics/install
-   quickstart
-   topics/tutorial
    topics/deployment
    topics/settings
    topics/customizing
@@ -60,6 +58,9 @@ Brief guides to areas of interest and importance when developing Horizon.
 .. toctree::
    :maxdepth: 1
 
+   intro
+   quickstart
+   topics/tutorial
    contributing
    testing
 

doc/source/intro.rst

@@ -1,9 +1,6 @@
-===================
+==============
-Introducing Horizon
+Horizon Basics
-===================
+==============
-
-.. contents:: Contents:
-   :local:
 
 Values
 ======

doc/source/quickstart.rst

@@ -1,6 +1,6 @@
-==================
+==========
-Horizon Quickstart
+Quickstart
-==================
+==========
 
 ..  Note ::
 
@@ -88,8 +88,12 @@ or to the IP and port the server is listening for.
     * Nova (compute, api, scheduler, and network)
     * Glance
     * Keystone
+    * Neutron (unless nova-network is used)
 
-    Optional support is provided for Swift.
+    Horizon provides optional support for other services.
+    See :ref:`system-requirements-label` for the supported services.
+    If Keystone endpoint for a service is configured, Horizon detects it
+    and enables its support automatically.
 
 
 Editing Horizon's Source

doc/source/topics/install.rst

@@ -0,0 +1,86 @@
+==================
+Installing Horizon
+==================
+
+This page covers the basic installation of Horizon.
+
+.. _system-requirements-label:
+
+System Requirements
+===================
+
+* Python 2.7 (or 2.6)
+* Django 1.6 (1.4 and 1.5 are supported too)
+* Minimum required set of running OpenStack services are:
+
+  * Nova
+  * Keystone
+  * Glance
+  * Neutron (unless nova-network is used)
+
+* All other services are optional.
+  Horizon supports the following services in Juno release.
+  If Keystone endpoint for a service is configured,
+  Horizon detects it and enables its support automatically.
+
+  * Swift
+  * Cinder
+  * Heat
+  * Ceilometer
+  * Trove
+  * Sahara
+
+Installation
+============
+
+1. Compile translation message catalogs for internationalization.
+   This step is not required if you do not need to support languages
+   other than English. GNU ``gettext`` tool is required to compile
+   message catalogs::
+
+    $ sudo apt-get install gettext
+    $ ./run_tests.sh --compilemessages
+
+   This command compiles translation message catalogs within Python
+   virtualenv named ``.venv``. After this step, you can remove
+   ``.venv`` directory safely.
+
+2. Install Horizon python module into your system. Run the following
+   in the top directory.::
+
+    $ sudo pip install .
+
+3. Create ``openstack_dashboard/local/local_settings.py``.
+   It is usually a good idea to copy
+   ``openstack_dashboard/local/local_settings.py.example`` and edit it.
+   At least we need to customize the following variables in this file.
+
+   * ``ALLOWED_HOSTS`` (unless ``DEBUG`` is ``True``)
+   * ``OPENSTACK_KEYSTONE_URL``
+
+   For more details, please refer to :doc:`deployment` and :doc:`settings`.
+
+4. Set up a web server with WSGI support.
+   It is optional but recommended in production deployments.
+   For example, install Apache web server on Ubuntu::
+
+    $ sudo apt-get install apache2 libapache2-mod-wsgi
+
+   Then configure the web server to host OpenStack Dashboard via WSGI.
+   For apache2 web server, you may need to create
+   ``/etc/apache2/site-available/horizon.conf``.
+   The template in devstack is a good example of the file.
+   http://git.openstack.org/cgit/openstack-dev/devstack/tree/files/apache-horizon.template
+
+5. Finally, enable the above configuration and restart the web server.::
+
+    $ sudo a2ensite horizon
+    $ sudo service apache2 restart
+
+Next Steps
+==========
+
+* :doc:`deployment` covers some common questions, concerns and pitfalls you
+  may encounter when deploying Horizon in a production environment.
+* :doc:`settings` lists the available settings for Horizon.
+* :doc:`customizing` describes how to customizing Horizon as you want.

doc/source/topics/settings.rst

@@ -1,6 +1,6 @@
-==================================
+==========================
-Horizon Settings and Configuration
+Settings and Configuration
-==================================
+==========================
 
 Introduction
 ============

doc/source/topics/tutorial.rst

@@ -1,6 +1,6 @@
-===================
+============================================
-Building on Horizon
+Tutorial: Building a Dashboard using Horizon
-===================
+============================================
 
 This tutorial covers how to use the various components in Horizon to build
 an example dashboard and a panel with a tab which has a table containing data