Add usage file to documentation

Add a usage file outlining how to create and manage
composed nodes using rsd_lib to the documentation.

Change-Id: I77417024991fbc3a5ca56e6721a814c6a549e0fc

doc/source/reference/index.rst

@@ -3,3 +3,8 @@ References
 ==========
 
 References of rsd-lib.
+
+.. toctree::
+   :maxdepth: 2
+
+   usage

doc/source/reference/usage.rst

@@ -0,0 +1,93 @@
+.. _usage:
+
+Using rsd-lib
+=============
+
+----------------------------------
+Composing and using a logical node
+----------------------------------
+
+.. code-block:: python
+
+  import rsd_lib
+
+  # Get a connection with the RSD endpoint
+  rsd = rsd_lib.RSDLib('http://localhost:8443/redfish/v1',
+                       username='foo', password='bar')
+
+  # Get the node collection object
+  node_col = rsd.get_node_collection()
+
+  # Get a list of existing composed nodes
+  node_col.get_members()
+
+  # Compose a new node with no requirements specified
+  node1 = node_col.compose_node()
+
+  # Compose a new node specifying requirements
+  node2 = node_col.compose_node(
+    name='testnode',
+    description='this is a node',
+    processor_req=[
+      {
+        'TotalCores': 4
+      }],
+    memory_req=[
+      {
+        'CapacityMiB': 8000,
+        'MemoryDeviceType': 'DDR'
+      }],
+    remote_drive_req=[
+      {
+        'CapacityGiB': 80,
+        'iSCSIAddress': 'iqn.oem.com:42',
+        'Master': {
+          'Type': 'Snapshot',
+          'Resource': '/redfish/v1/Services/1/LogicalDrives/1'
+        }
+      }]
+    )
+
+  # Get the python object for the node we created
+  node_inst = rsd.get_node(node1)
+
+  # Assemble the composed node (After allocation, node must be assembled)
+  node_inst.assemble_node()
+
+  # Refresh the node object
+  node_inst.refresh()
+
+  # Get composed node state of node, should be 'assembled'
+  print(node_inst.composed_node_state)
+
+  # Power the node ON
+  node_inst.reset_node(rsd_lib.RESET_ON)
+
+  # Get a list of allowed reset values
+  print(node_inst.get_allowed_reset_node_values())
+
+  # Refresh the node object
+  node_inst.refresh()
+
+  # Get the current power state
+  print(node_inst.power_state)
+
+  # Set the next boot device to boot once from PXE in UEFI mode
+  node_inst.set_node_boot_source(rsd_lib.BOOT_SOURCE_TARGET_PXE,
+                                 enabled=rsd_lib.BOOT_SOURCE_ENABLED_ONCE,
+                                 mode=rsd_lib.BOOT_SOURCE_MODE_UEFI)
+
+  # Get the current boot source information
+  print(node_inst.boot)
+
+  # Get a list of allowed boot source target values
+  print(node_inst.get_allowed_node_boot_source_values())
+
+  # Get the memory summary
+  print(node_inst.memory_summary)
+
+  # Get the processor summary
+  print(node_inst.processor_summary)
+
+  # Delete/Deallocate the composed node
+  node_inst.delete_node()