From d833d377cbd86b1f3cddb284c4ede24cbece3263 Mon Sep 17 00:00:00 2001
From: Steve Martinelli <stevemar@ca.ibm.com>
Date: Sat, 8 Aug 2015 01:07:07 -0700
Subject: [PATCH] Add developer documentation

OSC was missing developer docs, these are critically helpful for
new developers. Add sections related to running tests (tox,
functional and with the debugger), and generating docs locally.

implements bp: developer-documentation
Change-Id: I428d89c3e5fc335864bc4f7843506043ec332fe5
---
 doc/source/developing.rst | 89 +++++++++++++++++++++++++++++++++++++++
 doc/source/index.rst      | 10 ++++-
 2 files changed, 98 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/developing.rst

diff --git a/doc/source/developing.rst b/doc/source/developing.rst
new file mode 100644
index 0000000000..f13241f24e
--- /dev/null
+++ b/doc/source/developing.rst
@@ -0,0 +1,89 @@
+===============================
+Developing with OpenStackClient
+===============================
+
+Testing
+-------
+
+Using ``tox``
+=============
+
+Before running tests, you should have ``tox`` installed and available in your
+environment:
+
+.. code-block:: bash
+
+    $ pip install tox
+
+To execute the full suite of tests maintained within OpenStackClient, run:
+
+.. code-block:: bash
+
+    $ tox
+
+.. NOTE::
+
+    The first time you run ``tox``, it will take additional time to build
+    virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild
+    your virtualenv in a similar manner.
+
+To run tests for one or more specific test environments (for example, the most
+common configuration of Python 2.7 and PEP-8), list the environments with the
+``-e`` option, separated by spaces:
+
+.. code-block:: bash
+
+    $ tox -e py27,pep8
+
+See ``tox.ini`` for the full list of available test environments.
+
+Running functional tests
+========================
+
+OpenStackClient also maintains a set of functional tests that are optimally
+designed to be run against OpenStack's gate. Optionally, a developer may
+choose to run these tests against any OpenStack deployment, however depending
+on the services available, results will vary.
+
+To run the entire suite of functional tests:
+
+.. code-block:: bash
+
+    $ tox -e functional
+
+To run a specific functional test:
+
+.. code-block:: bash
+
+    $ tox -e functional -- --regex functional.tests.compute.v2.test_server
+
+Running with PDB
+================
+
+Using PDB breakpoints with ``tox`` and ``testr`` normally doesn't work since
+the tests fail with a `BdbQuit` exception rather than stopping at the
+breakpoint.
+
+To run with PDB breakpoints during testing, use the `debug` ``tox`` environment
+rather than ``py27``. Here's an example, passing the name of a test since
+you'll normally only want to run the test that hits your breakpoint:
+
+.. code-block:: bash
+
+    $ tox -e debug opentackclient.tests.identity.v3.test_group
+
+For reference, the `debug` ``tox`` environment implements the instructions
+here: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests
+
+
+Building the Documentation
+--------------------------
+
+The documentation is generated with Sphinx using the ``tox`` command. To
+create HTML docs, run the following:
+
+.. code-block:: bash
+
+    $ tox -e docs
+
+The resultant HTML will be the ``doc/build/html`` directory.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a3bc58e42a..c90b8e5296 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,7 +6,8 @@ OpenStackClient (aka OSC) is a command-line client for OpenStack that
 brings the command set for Compute, Identity, Image, Object Store and Volume
 APIs together in a single shell with a uniform command structure.
 
-Contents:
+User Documentation
+------------------
 
 .. toctree::
    :maxdepth: 1
@@ -29,6 +30,13 @@ Getting Started
 * Read the source `on OpenStack's Git server`_
 * Install OpenStackClient from `PyPi`_ or a `tarball`_
 
+Developer Documentation
+-----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   developing
 
 Project Goals
 -------------