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
This commit is contained in:
Steve Martinelli 2015-08-08 01:07:07 -07:00
parent 51ae8c78b9
commit d833d377cb
2 changed files with 98 additions and 1 deletions

89
doc/source/developing.rst Normal file
View File

@ -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.

View File

@ -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
-------------