[docs] Add documentation for config file

* Changed theme for readthedocs.

Change-Id: Idbfdd6b9e9fc0340074c3e0ea44394a5be18de61

doc/source/api.rst

@@ -1,6 +1,6 @@
-==========
-Public API
-==========
+=============
+API Reference
+=============
 
 .. automodule:: os_faults
     :members:

doc/source/cli.rst

@@ -2,4 +2,38 @@
 CLI reference
 =============
 
+
+os-inject-fault
+---------------
+
 .. program-output:: os-inject-fault --help
+
+
+os-faults
+---------
+
+.. program-output:: os-faults --help
+
+
+os-faults verify
+----------------
+
+.. program-output:: os-faults verify --help
+
+
+os-faults discover
+------------------
+
+.. program-output:: os-faults discover --help
+
+
+os-faults nodes
+---------------
+
+.. program-output:: os-faults nodes --help
+
+
+os-faults drivers
+-----------------
+
+.. program-output:: os-faults drivers --help

doc/source/conf.py

@@ -21,16 +21,21 @@ sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
 
+on_zuul = "ZUUL_PROJECT" in os.environ
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
     #'sphinx.ext.intersphinx',
     'sphinxcontrib.programoutput',
-    'oslosphinx',
     'ext.driver_doc',
 ]
 
+if on_zuul:
+    extensions.append('oslosphinx')
+
 version = os_faults.get_version()
 # The full version, including alpha/beta/rc tags.
 release = os_faults.get_release()
@@ -69,6 +74,8 @@ modindex_common_prefix = ['os_faults.']
 # html_theme_path = ["."]
 # html_theme = '_theme'
 # html_static_path = ['static']
+if not on_zuul:
+    html_theme = "sphinx_rtd_theme"
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project

doc/source/drivers.rst

@@ -26,8 +26,8 @@ Node discover
 .. driver_doc:: node_list
 
 
-Services
---------
+Service drivers
+---------------
 
 .. driver_doc:: process
 

doc/source/index.rst

@@ -13,13 +13,12 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
-   installation
-   usage
+   quickstart/index
    cli
-   api
    drivers
+   api
    contributing
 
 Release Notes

doc/source/quickstart/api.rst

@@ -1,56 +1,6 @@
-=====
-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>`_
-library:
-
-.. code-block:: python
-
-    cloud_config = {
-        'cloud_management': {
-            'driver': 'devstack',
-            'args': {
-                'address': 'devstack.local',
-                'username': 'root',
-            }
-        },
-        'power_managements': [
-            {
-                'driver': 'libvirt',
-                'args': {
-                    'connection_uri': 'qemu+unix:///system',
-                }
-            }
-        ]
-    }
-
-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()
-
+===
+API
+===
 
 The library operates with 2 types of objects:
 
@@ -63,6 +13,13 @@ Simplified API
 
 Simplified API is used to inject faults in a human-friendly form.
 
+.. code-block:: python
+
+    import os_faults
+    destructor = os_faults.connect(config_filename='os-faults.yaml')
+    os_faults.human_api(destructor, 'restart keystone service')
+
+
 **Service-oriented** command performs specified `action` against `service` on
 all, on one random node or on the node specified by FQDN::
 

doc/source/quickstart/basics.rst

@@ -0,0 +1,68 @@
+======
+Basics
+======
+
+
+Configuration file
+------------------
+
+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:: yaml
+
+    cloud_management:
+      driver: devstack
+      args:
+        address: 192.168.1.240
+        username: ubuntu
+        iface: enp0s3
+
+    power_managements:
+    - driver: libvirt
+      args:
+        connection_uri: qemu+ssh://ubuntu@10.0.1.50/system
+
+
+By default, the library reads configuration from a file and the file can be in
+the following three formats: ``os-faults.{json,yaml,yml}``. The configuration
+file will be searched in the default locations:
+
+    * current directory
+    * ~/.config/os-faults
+    * /etc/openstack
+
+Also, the configuration file can be specified in the ``OS_FAULTS_CONFIG``
+environment variable::
+
+    $ export OS_FAULTS_CONFIG=/home/alex/my-os-faults-config.yaml
+
+
+Running
+-------
+
+Establish a connection to the cloud and verify it:
+
+.. code-block:: python
+
+    import os_faults
+    destructor = os_faults.connect(config_filename='os-faults.yaml')
+    destructor.verify()
+
+
+or via CLI::
+
+    $ os-faults verify -c os-faults.yaml
+
+
+Make some destructive actions:
+
+.. code-block:: python
+
+    destructor.get_service(name='keystone').restart()
+
+
+or via CLI::
+
+    $ os-inject-fault -c os-faults.yaml restart keystone service

doc/source/quickstart/config_spec.rst

@@ -0,0 +1,158 @@
+===========================
+Configuration specification
+===========================
+
+Configuration file contains the following parameters:
+
+    * cloud_management
+    * power_managements
+    * node_discover
+    * services
+
+Each parameter specifies a driver or a list of drivers.
+
+Example configuration:
+
+.. code-block:: yaml
+
+    cloud_management:
+      driver: devstack
+      args:
+        address: 192.168.1.240
+        username: ubuntu
+        iface: enp0s3
+
+    power_managements:
+    - driver: libvirt
+      args:
+        connection_uri: qemu+ssh://ubuntu@10.0.1.50/system
+
+    - driver: ipmi
+      args:
+        fqdn_to_bmc:
+          node-1.domain.tld:
+            address: 120.10.30.65
+            username: alex
+            password: super-secret
+
+    node_discover:
+      driver: node_list
+      args:
+      - fqdn: node-1.domain.tld
+        ip: 192.168.1.240
+        mac: 1e:24:c3:75:dd:2c
+
+    services:
+      glance-api:
+        driver: screen
+        args:
+          grep: glance-api
+          window_name: g-api
+        hosts:
+        - 192.168.1.240
+
+
+cloud_management
+----------------
+
+This parameter specifies cloud managment driver and its argumanets.
+``cloud_management`` is responsible for configuring connection to nodes
+and contains arguments such as SSH username/password/key/proxy.
+
+.. code-block:: yaml
+
+    cloud_management:
+      driver: devstack  # name of the driver
+      args:             # arguments for the driver
+        address: 192.168.1.240
+        username: ubuntu
+        iface: enp0s3
+
+
+Also, such drivers can support discovering of cloud nodes. For example,
+``fuel``, ``tcpcloud`` drives allow discovering information about nodes
+through master/config node of the cloud.
+
+List of supported drivers for cloud_management: :ref:`Cloud management`
+
+
+power_managements
+-----------------
+
+This parameter specifies list of power management drivers. Such drivers
+allow controlling power state of cloud nodes.
+
+.. code-block:: yaml
+
+    power_managements:
+    - driver: libvirt   # name of the driver
+      args:             # arguments for the driver
+        connection_uri: qemu+ssh://ubuntu@10.0.1.50/system
+
+    - driver: ipmi      # name of the driver
+      args:             # arguments for the driver
+        fqdn_to_bmc:
+          node-1.domain.tld:
+            address: 120.10.30.65
+            username: alex
+            password: super-secret
+
+
+List of supported drivers for power_managements: :ref:`Power management`
+
+
+node_discover
+-------------
+
+This parameter specifies node discover driver. ``node_discover`` is responsible
+for fetching list of hosts for the cloud. If ``node_discover`` is specified in
+configuration then ``cloud_management`` will only control connection options to
+the nodes.
+
+.. code-block:: yaml
+
+    node_discover:
+      driver: node_list
+      args:
+      - fqdn: node-1.domain.tld
+        ip: 192.168.1.240
+        mac: 1e:24:c3:75:dd:2c
+
+List of supported drivers for node_discover: :ref:`Node discover`
+
+
+services
+--------
+
+This parameter specifies list of services and their types. This parameter
+allows updating/adding services which are embedded in ``cloud_management``
+driver.
+
+.. code-block:: yaml
+
+    services:
+      glance-api:            # name of the service
+        driver: screen       # name of the service driver
+        args:                # arguments for the driver
+          grep: glance-api
+          window_name: g-api
+        hosts:               # list of hosts where this service running
+        - 192.168.1.240
+      mysql:                 # name of the service
+        driver: process      # name of the service driver
+        args:                # arguments for the driver
+          grep: mysqld
+          port:
+          - tcp
+          - 3307
+          restart_cmd: sudo service mysql restart
+          start_cmd: sudo service mysql start
+          terminate_cmd: sudo service mysql stop
+
+
+Service driver contains optional ``hosts`` parameter which controls discovering
+of hosts where the service is running. If ``hosts`` specified, then service
+discovering is disabled for this service and hosts specified in ``hosts`` will
+be used, otherwise, service will be searched across all nodes.
+
+List of supported drivers for services: :ref:`Service drivers`

doc/source/quickstart/index.rst

@@ -0,0 +1,13 @@
+==========
+Quickstart
+==========
+
+This section describes how to start using os-faults.
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   basics
+   api
+   config_spec

test-requirements.txt

@@ -14,6 +14,7 @@ mock>=2.0 # BSD
 python-subunit>=0.0.18 # Apache-2.0/BSD
 sphinx>=1.5.1 # BSD
 sphinxcontrib-programoutput # BSD
+sphinx_rtd_theme # MIT
 oslosphinx>=4.7.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD

tox.ini

@@ -31,7 +31,7 @@ commands = flake8 . doc/ext
 
 [testenv:pep8-constraints]
 install_command = {[testenv:common-constraints]install_command}
-commands = flake8 . doc/ext
+commands = {[testenv:pep8]commands}
 
 [testenv:venv]
 commands = {posargs}
@@ -48,12 +48,12 @@ commands =
 
 [testenv:cover-constraints]
 install_command = {[testenv:common-constraints]install_command}
-commands = python setup.py test --coverage --testr-args='{posargs}'
+commands = {[testenv:cover]commands}
 
 [testenv:docs]
 commands =
     rm -rf doc/build
-    python setup.py build_sphinx
+    python setup.py build_sphinx --warning-is-error
 
 [testenv:releasenotes]
 commands =
@@ -61,14 +61,15 @@ commands =
 
 [testenv:docs-constraints]
 install_command = {[testenv:common-constraints]install_command}
-commands = python setup.py build_sphinx
+commands = {[testenv:docs]commands}
 
 [testenv:debug]
 commands = oslo_debug_helper {posargs}
 
 [testenv:debug-constraints]
 install_command = {[testenv:common-constraints]install_command}
-commands = oslo_debug_helper {posargs}
+commands = {[testenv:debug]commands}
+
 
 [flake8]
 # E123 skipped because it is ignored by default in the default pep8.