Browse Source

Add documentation

Change-Id: I9380316bcbbee6760ef13a91a93b489aee659a40
changes/99/288399/5
Imre Farkas 5 years ago
parent
commit
c35a60bba9
13 changed files with 418 additions and 10 deletions
  1. +20
    -0
      CONTRIBUTING.rst
  2. +4
    -0
      HACKING.rst
  3. +5
    -0
      README.rst
  4. +258
    -0
      doc/source/client-api.rst
  5. +74
    -0
      doc/source/conf.py
  6. +1
    -0
      doc/source/contributing.rst
  7. +17
    -0
      doc/source/index.rst
  8. +15
    -0
      doc/source/usage.rst
  9. +10
    -5
      dracclient/client.py
  10. +3
    -4
      dracclient/resources/job.py
  11. +5
    -0
      setup.cfg
  12. +2
    -0
      test-requirements.txt
  13. +4
    -1
      tox.ini

+ 20
- 0
CONTRIBUTING.rst View File

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

+ 4
- 0
HACKING.rst View File

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

+ 5
- 0
README.rst View File

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

+ 258
- 0
doc/source/client-api.rst View File

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

+ 74
- 0
doc/source/conf.py View File

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

+ 1
- 0
doc/source/contributing.rst View File

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

+ 17
- 0
doc/source/index.rst View File

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

+ 15
- 0
doc/source/usage.rst View File

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

+ 10
- 5
dracclient/client.py View File

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


+ 3
- 4
dracclient/resources/job.py View File

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


+ 5
- 0
setup.cfg View File

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

+ 2
- 0
test-requirements.txt View File

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

+ 4
- 1
tox.ini View File

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

Loading…
Cancel
Save