Minor documentation update

* Update the index page's description.
* Add a section about the hash ring to architecture.
* Add some new modules to, and remove some old modules from,
  the developer doc quick links, to make the list of quicklinks
  shorter and more useful.
* Correct a few broken links in the developer docs.

Change-Id: Ifac1dc355631a2d77b7ccdea362fb83ffbe6a4db

doc/source/dev/api.rst

@@ -5,7 +5,5 @@ Ironic's API Server
 ===========
 
 .. toctree::
-    ../api/ironic.api.config
-    ../api/ironic.api.controllers.root
-    ../api/ironic.api.controllers.v1
     ../api/ironic.api.hooks
+    ../api/ironic.api.controllers.root

doc/source/dev/architecture.rst

@@ -62,8 +62,26 @@ There are three categories of driver interfaces:
   will merely relay the message from the API service to the appropriate driver.
 
 
-.. _API service: ../dev/api-spec-v1.html
+Message Routing
+===============
+
+Each Conductor registers itself in the database upon start-up, and periodically
+updates the timestamp of its record. Contained within this registration is a
+list of the drivers which this Conductor instance supports.  This allows all
+services to maintain a consistent view of which Conductors and which drivers
+are available at all times.
+
+Based on their respective driver, all nodes are mapped across the set of
+available Conductors using a `consistent hashing algorithm`_. Node-specific
+tasks are dispatched from the API tier to the appropriate conductor using
+conductor-specific RPC channels.  As Conductor instances join or leave the
+cluster, nodes may be remapped to different Conductors, thus triggering various
+driver actions such as take-over or clean-up.
+
+
+.. _API service: ../webapi/v1.html
 .. _BaseDriver: ../api/ironic.drivers.base.html#ironic.drivers.base.BaseDriver
 .. _Conductor service: ../api/ironic.conductor.manager.html
 .. _DB API: ../api/ironic.db.api.html
 .. _diskimage-builder: https://github.com/openstack/diskimage-builder
+.. _consistent hashing algorithm: ../api/ironic.common.hash_ring.html

doc/source/dev/cmd.rst

@@ -1,10 +0,0 @@
-.. _cmd:
-
-==========================
-List of Installed Commands
-==========================
-
-.. toctree::
-    ../api/ironic.cmd.api
-    ../api/ironic.cmd.dbsync
-    ../api/ironic.cmd.conductor

doc/source/dev/common.rst

@@ -5,9 +5,10 @@ Common Modules and Utilities
 ============================
 
 .. toctree::
-    ../api/ironic.common.context
+    ../api/ironic.common.driver_factory
     ../api/ironic.common.exception
-    ../api/ironic.common.service
+    ../api/ironic.common.hash_ring
+    ../api/ironic.common.images
     ../api/ironic.common.states
     ../api/ironic.common.utils
 

doc/source/dev/db.rst

@@ -6,8 +6,4 @@ DB API Layer
 
 .. toctree::
     ../api/ironic.db.api
-    ../api/ironic.db.migration
-    ../api/ironic.db.models
-    ../api/ironic.db.sqlalchemy.api
-    ../api/ironic.db.sqlalchemy.migration
     ../api/ironic.db.sqlalchemy.models

doc/source/dev/drivers.rst

@@ -4,7 +4,17 @@
 Pluggable Drivers
 =================
 
+The IPMITool driver provides an interface to the command-line `ipmitool`_
+utility, whereas the IPMINative driver provides an interface to the newer
+`pyghmi`_ python library.
+
 .. toctree::
     ../api/ironic.drivers.base
-    ../api/ironic.drivers.fake
+    ../api/ironic.drivers.pxe
-    ../api/ironic.drivers.ipmi
+    ../api/ironic.drivers.modules.ipminative
+    ../api/ironic.drivers.modules.ipmitool
+    ../api/ironic.drivers.modules.pxe
+    ../api/ironic.drivers.modules.ssh
+
+.. _ipmitool: http://ipmitool.sourceforge.net/
+.. _pyghmi: https://github.com/stackforge/pyghmi

doc/source/index.rst

@@ -17,15 +17,19 @@ together multiple drivers, each of which implement some portion of that
 functionality with respect to physical hardware.
 
 For an in-depth look at the project's scope and structure, see the
-:doc:`dev/architecture` page.
+:doc:`developer/architecture` page.
 
 
-Status: Hard Hat Required!
+Status: Alpha Quality
-==========================
+=====================
 
-Ironic is under rapid initial development, forked from Nova's `Baremetal
+Ironic is targeting inclusion in the OpenStack Icehouse release. The current
-driver`_.  If you're looking for an OpenStack service to provision bare metal
+codebase should be considered "alpha" quality. All major functional components
-today, that is where you want to look.
+exist but there are many known bugs which will prevent general use at this
+time.  Additionally, usage documentation still needs to be written.
+
+If you are looking for the preceding baremetal service, which was included in
+OpenStack Grizzly and Havana releases, please see Nova's `Baremetal driver`_.
 
 .. TODO
 .. - installation
@@ -39,18 +43,18 @@ today, that is where you want to look.
 ..   - hw plugins
 
 
-Developer Docs
+Developer Documentation
-==============
+=======================
 
-For those wishing to develop Ironic itself, or add drivers to extend Ironic's
+Overview
-functionality, the following documentation is provided.
+--------
 
 .. toctree::
   :maxdepth: 1
 
-  dev/architecture
+  developer/architecture
-  dev/contributing
+  developer/contributing
-  dev/dev-quickstart
+  developer/dev-quickstart
 
 Client API Reference
 --------------------
@@ -64,14 +68,13 @@ Python API Quick Reference
 --------------------------
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 1
 
-  dev/api
+  developer/api
-  dev/cmd
+  developer/common
-  dev/common
+  developer/db
-  dev/db
+  developer/drivers
-  dev/drivers
+  developer/conductor
-  dev/conductor
 
 Indices and tables
 ==================