clean up the compute documentation a bit.

3 files changed, 96 insertions, 17 deletions

diff --git a/doc/source/compute.rst b/doc/source/compute.rst
index 93070fa88..737b2de98 100644
--- a/doc/source/compute.rst
+++ b/doc/source/compute.rst
@@ -16,9 +16,17 @@
       under the License.
 
 
+Compute
+=======
+
+This page contains the Compute Package documentation.
+
+
 from etherpad todo
 ------------------
 
+::
+
   * FIX RST IMPORT ERRORS
   * Compute Manager
     * public methods
@@ -30,57 +38,105 @@ from etherpad todo
     * hyperv implementation
 
 
-Compute Documentation
-=====================
+Manager
+-------
 
-This page contains the Compute Package documentation.
+Documentation for the compute manager and related files.  For reading about
+a specific virtualization backend, read Drivers_.
 
 
 The :mod:`manager` Module
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: nova.compute.manager
     :members:
     :undoc-members:
     :show-inheritance:
 
+
 The :mod:`disk` Module
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: nova.compute.disk
     :members:
     :undoc-members:
     :show-inheritance:
 
+
 The :mod:`instance_types` Module
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: nova.compute.instance_types
     :members:
     :undoc-members:
     :show-inheritance:
 
+
 The :mod:`power_state` Module
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: nova.compute.power_state
     :members:
     :undoc-members:
     :show-inheritance:
 
+
+Drivers
+-------
+
+
+Libvirt Implementations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Libvirt: KVM
+^^^^^^^^^^^^
+
+KVM Driver
+
+
+Libvirt: QEMU
+^^^^^^^^^^^^^
+
+QEMU Driver
+
+
+Libvirt: UML
+^^^^^^^^^^^^
+
+User Mode Linux Driver
+
+
+XEN
+~~~
+
+Xen Driver
+
+
+Hyper-V
+~~~~~~~
+
+Hyper-V Driver
+
+
+Monitoring
+----------
+
 The :mod:`monitor` Module
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: nova.compute.monitor
     :members:
     :undoc-members:
     :show-inheritance:
 
-RELATED TESTS
--------------
+
+Tests
+-----
+
 
 The :mod:`compute_unittest` Module
-----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: nova.tests.compute_unittest
     :members:
diff --git a/nova/compute/manager.py b/nova/compute/manager.py
index 574feec7c..c5102c35a 100644
--- a/nova/compute/manager.py
+++ b/nova/compute/manager.py
@@ -17,7 +17,20 @@
 #    under the License.
 
 """
-Handles all code relating to instances (guest vms)
+Handles all processes relating to instances (guest vms).
+
+The :py:class:`ComputeManager` class is a :py:class:`nova.manager.Manager` that
+handles RPC calls relating to creating instances.  It is responsible for
+building a disk image, launching it via the underlying virtualization driver,
+responding to calls to check it state, attaching persistent as well as termination.
+
+Related Flags
+-------------
+:instances_path:  Where instances are kept on disk
+:compute_driver:  Name of class that is used to handle virtualization, loaded
+                  by `nova.utils.import_object`
+:volume_manager:  Name of class that handles persistent storage, loaded by
+                  `nova.utils.import_object`
 """
 
 import datetime
@@ -40,12 +53,12 @@ flags.DEFINE_string('compute_driver', 'nova.virt.connection.get_connection',
 
 
 class ComputeManager(manager.Manager):
-    """
-    Manages the running instances.
-    """
+    """Manages the running instances from creation to destruction."""
+
     def __init__(self, compute_driver=None, *args, **kwargs):
         """Load configuration options and connect to the hypervisor."""
         # TODO(vish): sync driver creation logic with the rest of the system
+        #             and redocument the module docstring
         if not compute_driver:
             compute_driver = FLAGS.compute_driver
         self.driver = utils.import_object(compute_driver)
@@ -54,7 +67,7 @@ class ComputeManager(manager.Manager):
         super(ComputeManager, self).__init__(*args, **kwargs)
 
     def _update_state(self, context, instance_id):
-        """Update the state of an instance from the driver info"""
+        """Update the state of an instance from the driver info."""
         # FIXME(ja): include other fields from state?
         instance_ref = self.db.instance_get(context, instance_id)
         try:
@@ -67,6 +80,7 @@ class ComputeManager(manager.Manager):
     @defer.inlineCallbacks
     @exception.wrap_exception
     def refresh_security_group(self, context, security_group_id, **_kwargs):
+        """This call passes stright through to the virtualization driver."""
         yield self.driver.refresh_security_group(security_group_id)
 
     @defer.inlineCallbacks
diff --git a/nova/virt/connection.py b/nova/virt/connection.py
index 34e37adf7..ceb7f1e4b 100644
--- a/nova/virt/connection.py
+++ b/nova/virt/connection.py
@@ -17,7 +17,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""Abstraction of the underlying virtualization API"""
+"""Abstraction of the underlying virtualization API."""
 
 import logging
 import sys
@@ -39,6 +39,15 @@ def get_connection(read_only=False):
 
     Any object returned here must conform to the interface documented by
     FakeConnection.
+
+    Related flags
+    -------------
+    :connection_type:  A string literal that falls through a if/elif structure
+                       to determine what virtualization mechanism to use.
+                       Values may be:
+                            * fake
+                            * libvirt
+                            * xenapi
     """
     # TODO(termie): maybe lazy load after initial check for permissions
     # TODO(termie): check whether we can be disconnected