diff options
| -rw-r--r-- | doc/source/developing.rst | 89 | ||||
| -rw-r--r-- | doc/source/index.rst | 10 |
2 files changed, 98 insertions, 1 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index a3bc58e4..c90b8e52 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 ------------- |