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
-        submitted.
+        Once a config job has been submitted, it can no longer be abandoned.
 
         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
-                       created or not
+        :param reboot: indicates whether a RebootJob should also be created or
+                       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
-        submitted.
+        Once a config job has been submitted, it can no longer be abandoned.
 
         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