1 files changed, 89 insertions, 0 deletions
diff --git a/doc/source/developing.rst b/doc/source/developing.rst
new file mode 100644
index 00000000..f13241f2
--- /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.