1 files changed, 100 insertions, 0 deletions
diff --git a/docs/source/ref/run_tests.rst b/docs/source/ref/run_tests.rst
new file mode 100644
index 00000000..201198ed
--- /dev/null
+++ b/docs/source/ref/run_tests.rst
@@ -0,0 +1,100 @@
+===========================
+The ``run_tests.sh`` Script
+===========================
+
+Horizon ships with a script called ``run_tests.sh`` at the root of the
+repository. This script provides many crucial functions for the project,
+and also makes several otherwise complex tasks trivial for you as a
+developer.
+
+First Run
+=========
+
+If you start with a clean copy of the Horizon repository, the first thing
+you should do is to run ``./run_tests.sh`` from the root of the repository.
+This will do three things for you:
+
+    #. Set up a virtual environment for ``openstack-dashboard`` using
+       ``openstack-dashboard/tools/install_venv.py``.
+    #. Set up an environment for ``horizon`` using
+       ``horizon/bootstrap.py`` and ``horizon/bin/buildout``.
+    #. Run the tests for both ``horizon`` and ``openstack-dashboard`` using
+       their respective environments and verify that evreything is working.
+
+Setting up both environments the first time can take several minutes, but only
+needs to be done once. If dependencies are added in the future, updating the
+environments will be necessary but not necessarily as time consuming.
+
+I just want to run the tests!
+=============================
+
+Running both sets of unit tests quickly and easily is the main goal of this
+script. All you need to do is::
+
+    ./run_tests.sh
+
+Yep, that's it. Everything else the script can do is optional.
+
+Give me metrics!
+================
+
+You can generate various reports and metrics using command line arguments
+to ``run_tests.sh``.
+
+Coverage
+--------
+
+To run coverage reports::
+
+    ./run_tests.sh --coverage
+
+The reports are saved to ``./reports/`` and ``./coverage.xml``.
+
+PEP8
+----
+
+You can check for PEP8 violations as well::
+
+    ./run_tests.sh --pep8
+
+The results are saved to ``./pep8.txt``.
+
+PyLint
+------
+
+For more detailed code analysis you can run::
+
+    ./run_tests.sh --pylint
+
+The output will be saved in ``./pylint.txt``.
+
+Running the development server
+==============================
+
+As an added bonus, you can run Django's development server directly from
+the root of the repository with ``run_tests.sh`` like so::
+
+    ./run_tests.sh --runserver
+
+This is effectively just an alias for::
+
+    ./openstack-dashboard/tools/with_venv.sh ./openstack-dashboard/dashboard/manage.py runserver
+
+Generating the documentation
+============================
+
+You can build Horizon's documentation automatically by running::
+
+    ./run_tests.sh --docs
+
+The output is stored in ``./docs/build/html/``.
+
+Starting clean
+==============
+
+If you ever want to start clean with a new environment for Horizon, you can
+run::
+
+    ./run_tests.sh --force
+
+That will blow away the existing environments and create new ones for you.