Amending the quickstart guide

*Updating to avoid use of manage.py directly.
*Making it more DevStack friendly.
*Adding a sample DevStack local.conf to allow for exercise Horizon
 against more services.
*Added simple developer instructions so new developers aren't tempted
 to work on the DevStack instance of Horizon.

Change-Id: I0840c63183e7cec3b08e4f2ce208479ff7552f60

3 files changed, 125 insertions, 12 deletions

diff --git a/doc/source/index.rst b/doc/source/index.rst
index cb5f8e069..536173bb8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -96,6 +96,7 @@ In-depth documentation for Horizon and its APIs.
    ref/decorators
    ref/exceptions
    ref/test
+   ref/local_conf
 
 Source Code Reference
 ---------------------
diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst
index 77551be4c..92c8e6dc3 100644
--- a/doc/source/quickstart.rst
+++ b/doc/source/quickstart.rst
@@ -30,6 +30,13 @@ repository from http://github.com/openstack/horizon and execute the
     > cd horizon
     > ./run_tests.sh
 
+.. note::
+
+    Running ``run_tests.sh`` will build a virtualenv, ``.venv``, where all the
+    python dependencies for Horizon are installed and referenced. After the
+    dependencies are installed, the unit test suites in the Horizon repo will be
+    executed.  There should be no errors from the tests.
+
 Next you will need to setup your Django application config by copying ``openstack_dashboard/local/local_settings.py.example`` to ``openstack_dashboard/local/local_settings.py``. To do this quickly you can use the following command::
 
     > cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py
@@ -39,32 +46,39 @@ Next you will need to setup your Django application config by copying ``openstac
     To add new settings or customize existing settings, modify the ``local_settings.py`` file.
 
 Horizon assumes a single end-point for OpenStack services which defaults to
-the local host (127.0.0.1). If this is not the case change the
-``OPENSTACK_HOST`` setting in the ``openstack_dashboard/local/local_settings.py`` file, to the actual IP address of the OpenStack end-point Horizon should use.
+the local host (127.0.0.1), as is the default in DevStack. If this is not the
+case change the ``OPENSTACK_HOST`` setting in the
+``openstack_dashboard/local/local_settings.py`` file, to the actual IP address
+of the OpenStack end-point Horizon should use.
 
-To start the Horizon development server use the Django ``manage.py`` utility
-with the context of the virtual environment::
+To start the Horizon development server use ``run_tests.sh``::
 
-    > tools/with_venv.sh ./manage.py runserver
+    > ./run_tests.sh --runserver localhost:9000
 
-Alternately specify the listen IP and port::
+.. note::
 
-    > tools/with_venv.sh ./manage.py runserver 0.0.0.0:8080
+    The default port for runserver is 8000 which is already consumed by
+    heat-api-cfn in DevStack. If not running in DevStack
+    `./run_tests.sh --runserver` will start the test server at
+    `http://localhost:8000`.
 
-.. note::
 
-    If you would like to run commands without the prefix of ``tools/with_venv.sh`` you may source your environment directly. This will remain active as long as your shell session stays open::
+.. note::
 
-    > source .venv/bin/activate
+    The ``run_tests.sh`` script provides wrappers around ``manage.py``.
+    For more information on manage.py which is a django, see
+    `https://docs.djangoproject.com/en/dev/ref/django-admin/`
 
 
-Once the Horizon server is running point a web browser to http://localhost:8000
+Once the Horizon server is running, point a web browser to http://localhost:9000
 or to the IP and port the server is listening for.
 
 .. note::
 
     The ``DevStack`` project (http://devstack.org/) can be used to install
-    an OpenStack development environment from scratch.
+    an OpenStack development environment from scratch. For a local.conf that
+    enables most services that Horizon supports managing see
+    :doc:`local.conf <ref/local_conf>`
 
 .. note::
 
@@ -77,6 +91,31 @@ or to the IP and port the server is listening for.
 
     Optional support is provided for Swift.
 
+
+Editing Horizon's Source
+========================
+
+Although DevStack installs and configures an instance of Horizon when running
+stack.sh, the preferred development setup follows the instructions above on the
+server/VM running DevStack. The are several advantages to maintaining a
+separate copy of the Horizon repo, rather than editing the devstack installed
+copy.
+
+    * Source code changes aren't as easily lost when running unstack.sh/stack.sh
+    * The development server picks up source code changes (other than JavaScript
+      and CSS due to compression and compilation) while still running.
+    * Log messages and print statements go directly to the console.
+    * Debugging with pdb becomes much simpler to interact with.
+
+.. Note::
+    JavaScript and CSS changes require a development server restart. Also,
+    forcing a refresh of the page (e.g. using Shift-F5) in the browser is
+    required to pull down non-cached versions of the CSS and JavaScript. The
+    default setting in Horizon is to do compilation and compression of these
+    files at server startup. If you have configured your local copy to do
+    offline compression, more steps are required.
+
+
 Horizon's Structure
 ===================
 
diff --git a/doc/source/ref/local_conf.rst b/doc/source/ref/local_conf.rst
new file mode 100644
index 000000000..3061c9cbd
--- /dev/null
+++ b/doc/source/ref/local_conf.rst
@@ -0,0 +1,73 @@
+==========
+local.conf
+==========
+
+Configuring DevStack for Horizon
+================================
+
+Place the following content into `devstack/local.conf` to start the services
+that Horizon supports in DevStack when `stack.sh` is run.
+::
+
+    [[local|localrc]]
+
+    ADMIN_PASSWORD=pass
+    MYSQL_PASSWORD=pass
+    RABBIT_PASSWORD=pass
+    SERVICE_PASSWORD=pass
+    SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50
+
+    # Recloning will insure that your stack is up to date. The downside
+    # is overhead on restarts and potentially losing a stable environment.
+    # If set to yes, will reclone all repos every time stack.sh is run.
+    # The default is no.
+    #RECLONE=yes
+
+    # Note: there are several network setting changes that may be
+    # required to get networking properly configured in your environment.
+    # This file is just using the defaults set up by devstack.
+    # For a more detailed treatment of devstack network configuration
+    # options, please see: http://devstack.org/guides/single-machine.html
+
+    # Enable Swift (object-store) Service without replication
+    enable_service s-proxy s-object s-container s-account
+    SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5
+    SWIFT_REPLICAS=1
+    SWIFT_DATA_DIR=$DEST/data/swift
+
+    # enabling Neutron (network) Service
+    # to use nova net rather than neutron, comment out the following group
+    disable_service n-net
+    enable_service q-svc
+    enable_service q-agt
+    enable_service q-dhcp
+    enable_service q-13
+    enable_service q-meta
+    enable_service q-metering
+    enable_service neutron
+    enable_service q-lbaas
+    enable_service q-fwaas
+    enable_service q-vpn
+    # end group
+
+    # enable Heat (orchestration) Service
+    enable_service heat h-api h-api-cfn h-api-cw h-eng
+
+    # enable Sahara (data_processing) Service
+    enable_service sahara
+
+    # enable Trove (database) Service
+    enable_service trove tr-api tr-tmgr tr-cond
+
+    # enable Ceilometer (metering) Service
+    enable_service ceilometer-acompute ceilometer-acentral ceilometer-anotification ceilometer-collector ceilometer-api
+
+
+    # Set ``OFFLINE`` to ``True`` to configure ``stack.sh`` to run cleanly without
+    # Internet access. ``stack.sh`` must have been previously run with Internet
+    # access to install prerequisites and fetch repositories.
+    # OFFLINE=True
+
+    [[post-config|$GLANCE_API_CONF]]
+    [DEFAULT]
+    default_store=file