Add usage and API reference into docs

Change-Id: I7edaaec1077768be9469c639551d499e8ba9d9df

README.rst

@@ -2,7 +2,7 @@
 OS-Faults
 =========
 
-**OpenStack faults injection library**
+**OpenStack fault-injection library**
 
 The library does destructive actions inside an OpenStack cloud. It provides
 an abstraction layer over different types of cloud deployments. The actions
@@ -14,8 +14,8 @@ IPMI driver).
 * Source: https://github.com/openstack/os-faults
 * Bugs: http://bugs.launchpad.net/os-faults
 
-Usage
------
+Configuration
+-------------
 
 The cloud deployment configuration schema is an extension to the cloud config
 used by the `os-client-config <https://github.com/openstack/os-client-config>`_

doc/source/api.rst

@@ -0,0 +1,15 @@
+==========
+Public API
+==========
+
+.. automodule:: os_faults
+    :members:
+
+.. autoclass:: os_faults.api.cloud_management.CloudManagement
+    :members:
+
+.. autoclass:: os_faults.api.service.Service
+    :members:
+
+.. autoclass:: os_faults.api.node_collection.NodeCollection
+    :members:

doc/source/cli.rst

@@ -0,0 +1,5 @@
+=============
+CLI reference
+=============
+
+.. program-output:: os-inject-fault --help

doc/source/conf.py

@@ -23,6 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
+    'sphinxcontrib.programoutput',
     'oslosphinx'
 ]
 
@@ -50,6 +51,9 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# A list of ignored prefixes for module index sorting.
+modindex_common_prefix = ['os_faults.']
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with

doc/source/history.rst

@@ -0,0 +1 @@
+.. include:: ../../ChangeLog

doc/source/index.rst

@@ -1,22 +1,35 @@
-.. os-faults documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+=========
+OS-Faults
+=========
 
-Welcome to os-faults's documentation!
-=====================================
+**OpenStack fault-injection library**
 
-Contents:
+The library does destructive actions inside an OpenStack cloud. It provides
+an abstraction layer over different types of cloud deployments. The actions
+are implemented as drivers (e.g. DevStack driver, Fuel driver, Libvirt driver,
+IPMI driver).
+
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
    usage
+   cli
+   api
    contributing
 
-Indices and tables
+Release Notes
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   history
+
+Indices and Tables
 ==================
 
 * :ref:`genindex`

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

doc/source/usage.rst

@@ -2,6 +2,160 @@
 Usage
 =====
 
-To use os-faults in a project::
+Configuration
+-------------
 
-    import os_faults
+The cloud deployment configuration schema is an extension to the cloud config
+used by the `os-client-config <https://github.com/openstack/os-client-config>`_
+library:
+
+.. code-block:: python
+
+    cloud_config = {
+        'cloud_management': {
+            'driver': 'devstack',
+            'address': 'devstack.local',
+            'username': 'root',
+        },
+        'power_management': {
+            'driver': 'libvirt',
+            'address': 'host.local',
+            'username': 'root',
+        }
+    }
+
+Establish a connection to the cloud and verify it:
+
+.. code-block:: python
+
+    destructor = os_faults.connect(cloud_config)
+    destructor.verify()
+
+The library can also read configuration from a file and the file can be in the
+following three formats: os-faults.{json,yaml,yml}. The configuration file can
+be specified in the `OS_FAULTS_CONFIG` environment variable or can be read from
+one of the default locations:
+
+    * current directory
+    * ~/.config/os-faults
+    * /etc/openstack
+
+Make some destructive actions:
+
+.. code-block:: python
+
+    destructor.get_service(name='keystone').restart()
+
+
+The library operates with 2 types of objects:
+
+    * `service` - is a software that runs in the cloud, e.g. `nova-api`
+    * `nodes` - nodes that host the cloud, e.g. a hardware server with a hostname
+
+
+Simplified API
+--------------
+
+Simplified API is used to inject faults in a human-friendly form.
+
+**Service-oriented** command performs specified `action` against `service` on
+all, on one random node or on the node specified by FQDN::
+
+    <action> <service> service [on (random|one|single|<fqdn> node[s])]
+
+Examples:
+    * `Restart Keystone service` - restarts Keystone service on all nodes.
+    * `kill nova-api service on one node` - restarts Nova API on one
+      randomly-picked node.
+
+**Node-oriented** command performs specified `action` on node specified by FQDN
+or set of service's nodes::
+
+    <action> [random|one|single|<fqdn>] node[s] [with <service> service]
+
+Examples:
+    * `Reboot one node with mysql` - reboots one random node with MySQL.
+    * `Reset node-2.domain.tld node` - reset node `node-2.domain.tld`.
+
+**Network-oriented** command is a subset of node-oriented and performs network
+management operation on selected nodes::
+
+    <action> <network> network on [random|one|single|<fqdn>] node[s]
+        [with <service> service]
+
+Examples:
+    * `Disconnect management network on nodes with rabbitmq service` - shuts
+      down management network interface on all nodes where rabbitmq runs.
+    * `Connect storage network on node-1.domain.tld node` - enables storage
+      network interface on node-1.domain.tld.
+
+
+Extended API
+------------
+
+1. Service actions
+~~~~~~~~~~~~~~~~~~
+
+Get a service and restart it:
+
+.. code-block:: python
+
+    destructor = os_faults.connect(cloud_config)
+    service = destructor.get_service(name='glance-api')
+    service.restart()
+
+Available actions:
+ * `start` - start Service
+ * `terminate` - terminate Service gracefully
+ * `restart` - restart Service
+ * `kill` - terminate Service abruptly
+ * `unplug` - unplug Service out of network
+ * `plug` - plug Service into network
+
+2. Node actions
+~~~~~~~~~~~~~~~
+
+Get all nodes in the cloud and reboot them:
+
+.. code-block:: python
+
+    nodes = destructor.get_nodes()
+    nodes.reboot()
+
+Available actions:
+ * `reboot` - reboot all nodes gracefully
+ * `poweroff` - power off all nodes abruptly
+ * `reset` - reset (cold restart) all nodes
+ * `oom` - fill all node's RAM
+ * `disconnect` - disable network with the specified name on all nodes
+ * `connect` - enable network with the specified name on all nodes
+
+3. Operate with nodes
+~~~~~~~~~~~~~~~~~~~~~
+
+Get all nodes where a service runs, pick one of them and reset:
+
+.. code-block:: python
+
+    nodes = service.get_nodes()
+    one = nodes.pick()
+    one.reset()
+
+Get nodes where l3-agent runs and disable the management network on them:
+
+.. code-block:: python
+
+    fqdns = neutron.l3_agent_list_hosting_router(router_id)
+    nodes = destructor.get_nodes(fqdns=fqdns)
+    nodes.disconnect(network_name='management')
+
+4. Operate with services
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Restart a service on a single node:
+
+.. code-block:: python
+
+    service = destructor.get_service(name='keystone')
+    nodes = service.get_nodes().pick()
+    service.restart(nodes)

os_faults/__init__.py

@@ -65,6 +65,12 @@ def _init_driver(params):
 
 
 def connect(cloud_config=None, config_filename=None):
+    """Connect to the cloud
+
+    :param cloud_config: dict with cloud and power management params
+    :param config_filename: name of the file where to read config from
+    :return: CloudManagement object
+    """
     if not cloud_config:
         cloud_config = _read_config(config_filename)
 

setup.cfg

@@ -1,11 +1,11 @@
 [metadata]
 name = os_faults
-summary = OpenStack failures library
+summary = OpenStack fault-injection library
 description-file =
     README.rst
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
-home-page = http://www.openstack.org/
+home-page = http://os-faults.readthedocs.io/
 classifier =
     Environment :: OpenStack
     Intended Audience :: Information Technology

test-requirements.txt

@@ -12,8 +12,9 @@ coverage>=3.6
 ddt>=1.0.1
 mock>=1.2
 python-subunit>=0.0.18
-sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
-oslosphinx>=2.5.0 # Apache-2.0
+sphinx!=1.3b1,<1.4,>=1.2.1 # BSD
+sphinxcontrib-programoutput
+oslosphinx>=4.7.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 testrepository>=0.0.18
 testscenarios>=0.4