Add documentation

Change-Id: I9380316bcbbee6760ef13a91a93b489aee659a40

CONTRIBUTING.rst

@@ -0,0 +1,20 @@
+Contributing
+------------
+
+If you would like to contribute to the development of OpenStack, you must
+follow the steps in this page:
+
+   http://docs.openstack.org/infra/manual/developers.html
+
+If you already have a good understanding of how the system works and your
+OpenStack accounts are set up, you can skip to the development workflow
+section of this documentation to learn how changes to OpenStack should be
+submitted for review via the Gerrit tool:
+
+   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Pull requests submitted through GitHub will be ignored.
+
+Bugs should be filed on Launchpad, not GitHub:
+
+   https://bugs.launchpad.net/python-dracclient

HACKING.rst

@@ -0,0 +1,4 @@
+python-dracclient Style Commandments
+====================================
+
+Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/

README.rst

@@ -2,3 +2,8 @@ python-dracclient
 =================
 
 Library for managing machines with Dell iDRAC cards.
+
+* Free software: Apache license
+* Documentation: http://docs.openstack.org/developer/python-dracclient
+* Source: http://git.openstack.org/cgit/openstack/python-dracclient
+* Bugs: http://bugs.launchpad.net/python-dracclient

doc/source/client-api.rst

@@ -0,0 +1,258 @@
+Client API
+==========
+
+
+Power management
+----------------
+
+get_power_state
+~~~~~~~~~~~~~~~
+Returns the current power state of the node.
+
+set_power_state
+~~~~~~~~~~~~~~~
+Turns the server power on/off or do a reboot.
+
+Required parameters:
+
+* ``target_state``: target power state. Valid options are: ``POWER_ON``,
+  ``POWER_OFF`` and ``REBOOT``.
+
+
+Boot management
+---------------
+
+list_boot_modes
+~~~~~~~~~~~~~~~
+Returns the list of boot modes.
+
+list_boot_devices
+~~~~~~~~~~~~~~~~~
+Returns the list of boot devices.
+
+change_boot_device_order
+~~~~~~~~~~~~~~~~~~~~~~~~
+Changes the boot device sequence for a boot mode.
+
+Required parameters:
+
+* ``boot_mode``: boot mode for which the boot device list is to be changed.
+
+* ``boot_device_list``: a list of boot device ids in an order representing the
+  desired boot sequence.
+
+
+BIOS configuration
+------------------
+
+list_bios_settings
+~~~~~~~~~~~~~~~~~~
+Lists the BIOS configuration settings.
+
+set_bios_settings
+~~~~~~~~~~~~~~~~~
+Sets the BIOS configuration. To be more precise, it sets the ``pending_value``
+parameter for each of the attributes passed in. It returns a dictionary
+containing the ``commit_needed`` key with a boolean value indicating whether a
+config job must be created for the values to be applied.
+
+Required parameters:
+
+* ``settings``: a dictionary containing the proposed values, with each key
+  being the name of attribute and the value being the proposed value.
+
+commit_pending_bios_changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Applies all pending changes on the BIOS by creating a config job and returns
+the id of the created job.
+
+Optional parameters:
+
+* ``reboot``: indicates whether a RebootJob should also be created or not.
+  Defaults to ``False``.
+
+abandon_pending_bios_changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes all pending changes on the BIOS.
+
+.. note::
+    Once a config job has been submitted, it can no longer be abandoned.
+
+RAID management
+---------------
+
+list_raid_controllers
+~~~~~~~~~~~~~~~~~~~~~
+Returns the list of RAID controllers.
+
+list_virtual_disks
+~~~~~~~~~~~~~~~~~~
+Returns the list of RAID arrays.
+
+list_physical_disks
+~~~~~~~~~~~~~~~~~~~
+Returns the list of physical disks.
+
+create_virtual_disk
+~~~~~~~~~~~~~~~~~~~
+Creates a virtual disk and returns a dictionary containing the
+``commit_needed`` key with a boolean value indicating whether a config job must
+be created for the values to be applied.
+
+.. note::
+    The created virtual disk will be in pending state.
+
+Required parameters:
+
+* ``raid_controller``: id of the RAID controller.
+
+* ``physical_disks``: ids of the physical disks.
+
+* ``raid_level``: RAID level of the virtual disk.
+
+* ``size_mb``: size of the virtual disk in megabytes.
+
+Optional parameters:
+
+* ``disk_name``: name of the virtual disk.
+
+* ``span_length``: number of disks per span.
+
+* ``span_depth``: number of spans in virtual disk.
+
+delete_virtual_disk
+~~~~~~~~~~~~~~~~~~~
+Deletes a virtual disk and returns a dictionary containing the
+``commit_needed`` key with a boolean value indicating whether a config job must
+be created for the values to be applied.
+
+.. note::
+    The deleted virtual disk will be in pending state. For the changes to be
+    applied, a config job must be created and the node must be rebooted.
+
+Required parameters:
+
+* ``virtual_disk``: id of the virtual disk.
+
+commit_pending_raid_changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Applies all pending changes on a RAID controller by creating a config job and
+returns the id of the created job.
+
+Required parameters:
+
+* ``raid_controller``: id of the RAID controller.
+
+Optional parameters:
+
+* ``reboot``: indicates whether a RebootJob should also be created or not.
+  Defaults to ``False``.
+
+abandon_pending_raid_changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes all pending changes on a RAID controller.
+
+.. note::
+    Once a config job has been submitted, it can no longer be abandoned.
+
+Required parameters:
+
+* ``raid_controller``: id of the RAID controller.
+
+
+Job management
+--------------
+
+list_jobs
+~~~~~~~~~
+Returns a list of jobs from the job queue.
+
+Optional parameters:
+
+* ``only_unfinished``: indicates whether only unfinished jobs should be
+  returned. Defaults to ``False``.
+
+get_job
+~~~~~~~
+Returns a job from the job queue.
+
+Required parameters:
+
+* ``job_id``: id of the job.
+
+create_config_job
+~~~~~~~~~~~~~~~~~
+Creates a config job and returns the id of the created job.
+
+.. note::
+    In CIM (Common Information Model), weak association is used to name an
+    instance of one class in the context of an instance of another class.
+    ``SystemName`` and ``SystemCreationClassName`` are the attributes of the
+    scoping system, while ``Name`` and ``CreationClassName`` are the attributes
+    of the instance of the class, on which the ``CreateTargetedConfigJob``
+    method is invoked.
+
+Required parameters:
+
+* ``resource_uri``: URI of resource to invoke.
+
+* ``cim_creation_class_name``: creation class name of the CIM object.
+
+* ``cim_name``: name of the CIM object.
+
+* ``target``: target device.
+
+Optional parameters:
+
+* ``cim_system_creation_class_name``: creation class name of the scoping
+  system. Defaults to ``DCIM_ComputerSystem``.
+
+* ``cim_system_name``: name of the scoping system. Defaults to
+  ``DCIM:ComputerSystem``.
+
+* ``reboot``: indicates whether a RebootJob should also be created or not.
+  Defaults to ``False``.
+
+delete_pending_config
+~~~~~~~~~~~~~~~~~~~~~
+Cancels pending configuration.
+
+.. note::
+    Once a config job has been submitted, it can no longer be abandoned.
+
+.. note::
+    In CIM (Common Information Model), weak association is used to name an
+    instance of one class in the context of an instance of another class.
+    ``SystemName`` and ``SystemCreationClassName`` are the attributes of the
+    scoping system, while ``Name`` and ``CreationClassName`` are the attributes
+    of the instance of the class, on which the ``CreateTargetedConfigJob``
+    method is invoked.
+
+Required parameters:
+
+* ``resource_uri``: URI of resource to invoke.
+
+* ``cim_creation_class_name``: creation class name of the CIM object.
+
+* ``cim_name``: name of the CIM object.
+
+* ``target``: target device.
+
+Optional parameters:
+
+* ``cim_system_creation_class_name``: creation class name of the scoping
+  system. Defaults to ``DCIM_ComputerSystem``.
+
+* ``cim_system_name``: name of the scoping system. Defaults to
+  ``DCIM:ComputerSystem``.
+
+* ``reboot``: indicates whether a RebootJob should also be created or not.
+  Defaults to ``False``.
+
+
+Lifecycle controller management
+-------------------------------
+
+get_lifecycle_controller_version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Returns the Lifecycle controller version as a tuple of integers.

doc/source/conf.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+# -- General configuration ----------------------------------------------------
+
+# 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',
+    'oslosphinx'
+]
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'python-dracclient'
+copyright = u'OpenStack Foundation'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+# html_static_path = ['static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     '%s.tex' % project,
+     u'%s Documentation' % project,
+     u'OpenStack Foundation', 'manual'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+#intersphinx_mapping = {'http://docs.python.org/': None}

doc/source/contributing.rst

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

doc/source/index.rst

@@ -0,0 +1,17 @@
+Welcome to python-dracclient's documentation!
+=============================================
+
+Contents:
+
+.. toctree::
+
+  Usage <usage>
+  Client API <client-api>
+  Contributing <contributing>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/usage.rst

@@ -0,0 +1,15 @@
+Usage
+-----
+
+Create a client object by providing the connection details of the DRAC card::
+
+    client = wsmanclient.client.DRACClient('1.2.3.4', 'username', 's3cr3t')
+
+.. note::
+    By default it will use port 443, '/wsman' as path and https protocol.
+
+You can override the default port, path and protocol::
+
+    client = wsmanclient.client.DRACClient('1.2.3.4', 'username', 's3cr3t',
+                                           port=443, path='/wsman',
+                                           protocol='https')

dracclient/client.py

@@ -200,7 +200,7 @@ class DRACClient(object):
         :param cim_system_creation_class_name: creation class name of the
                                                scoping system
         :param cim_system_name: name of the scoping system
-        :param reboot: indicates whether a RebootJob should be also be
+        :param reboot: indicates whether a RebootJob should also be
                        created or not
         :returns: id of the created job
         :raises: WSManRequestFailure on request failures
@@ -219,8 +219,7 @@ class DRACClient(object):
             cim_system_name='DCIM:ComputerSystem'):
         """Cancels pending configuration
 
-        Configuration can only be canceled until a config job hasn't been
+        Once a config job has been submitted, it can no longer be abandoned.
-        submitted.
 
         In CIM (Common Information Model), weak association is used to name an
         instance of one class in the context of an instance of another class.
@@ -249,7 +248,7 @@ class DRACClient(object):
     def commit_pending_bios_changes(self, reboot=False):
         """Applies all pending changes on the BIOS by creating a config job
 
-        :param reboot: indicates whether a RebootJob should be also be
+        :param reboot: indicates whether a RebootJob should also be
                        created or not
         :returns: id of the created job
         :raises: WSManRequestFailure on request failures
@@ -267,6 +266,8 @@ class DRACClient(object):
     def abandon_pending_bios_changes(self):
         """Deletes all pending changes on the BIOS
 
+        Once a config job has been submitted, it can no longer be abandoned.
+
         :raises: WSManRequestFailure on request failures
         :raises: WSManInvalidResponse when receiving invalid response
         :raises: DRACOperationFailed on error reported back by the DRAC
@@ -374,7 +375,8 @@ class DRACClient(object):
 
          ...by creating a config job.
 
-        :param reboot: indicates whether a RebootJob should be also be
+        :param raid_controller: id of the RAID controller
+        :param reboot: indicates whether a RebootJob should also be
                        created or not
         :returns: id of the created job
         :raises: WSManRequestFailure on request failures
@@ -391,6 +393,9 @@ class DRACClient(object):
     def abandon_pending_raid_changes(self, raid_controller):
         """Deletes all pending changes on a RAID controller
 
+        Once a config job has been submitted, it can no longer be abandoned.
+
+        :param raid_controller: id of the RAID controller
         :raises: WSManRequestFailure on request failures
         :raises: WSManInvalidResponse when receiving invalid response
         :raises: DRACOperationFailed on error reported back by the DRAC

dracclient/resources/job.py

@@ -103,8 +103,8 @@ class JobManagement(object):
         :param cim_system_creation_class_name: creation class name of the
                                                scoping system
         :param cim_system_name: name of the scoping system
-        :param reboot: indicates whether a RebootJob should be also be
+        :param reboot: indicates whether a RebootJob should also be created or
-                       created or not
+                       not
         :returns: id of the created job
         :raises: WSManRequestFailure on request failures
         :raises: WSManInvalidResponse when receiving invalid response
@@ -142,8 +142,7 @@ class JobManagement(object):
             cim_system_name='DCIM:ComputerSystem'):
         """Cancels pending configuration
 
-        Configuration can only be canceled until a config job hasn't been
+        Once a config job has been submitted, it can no longer be abandoned.
-        submitted.
 
         In CIM (Common Information Model), weak association is used to name an
         instance of one class in the context of an instance of another class.

setup.cfg

@@ -21,3 +21,8 @@ classifier =
 [files]
 packages =
     dracclient
+
+[build_sphinx]
+all_files = 1
+build-dir = doc/build
+source-dir = doc/source

test-requirements.txt

@@ -7,3 +7,5 @@ doc8
 hacking>=0.10.0,<0.11
 mock>=1.2
 requests-mock>=0.6
+sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
+oslosphinx>=2.5.0 # Apache-2.0

tox.ini

@@ -18,7 +18,10 @@ commands = {posargs}
 basepython = python2.7
 commands =
     flake8 dracclient
-    doc8 README.rst
+    doc8 README.rst CONTRIBUTING.rst doc/source
+
+[testenv:docs]
+commands = python setup.py build_sphinx
 
 [flake8]
 max-complexity=15