Some minor clean up of various doc pages

* simplify the links on index.rst
* update the main description on the index page

* move install/ironic-install under deploy/
* rename ironic-install to install-guide
* rename userguide to user-guide
* clarify a few things in the install-guide

Change-Id: Ic6eff035df42d0c3fa78f54eac7ad8322ebb0afc

doc/source/deploy/install-guide.rst

@@ -1,8 +1,11 @@
-.. _ironic-install:
+.. _install-guide:
 
-===========================
+=====================================
-Bare Metal Service Overview
+Bare Metal Service Installation Guide
-===========================
+=====================================
+
+Service Overview
+================
 
 The Bare Metal Service is a collection of components that provides support to
 manage and provision physical machines.
@@ -25,22 +28,25 @@ The Bare Metal Service includes the following components:
   ipmi or ssh; provisions/deploys/decommissions bare metal nodes.
 - Ironic client. A command-line interface (CLI) for interacting with
   the Bare Metal Service.
-- Database. Stores node-related information. You can set the database
+
-  backend type and location,
+Additionally, the Bare Metal Servive has certain external dependencies, which are
-  but it is typically set to use the same database backend as the
+very similar to other OpenStack Services:
-  Compute Service.
+
+- A database to store hardware information and state. You can set the database
+  backend type and location. A simple approach is to use the same database
+  backend as the Compute Service. Another approach is to use a separate
+  database backend to further isolate bare metal resources (and associated
+  metadata) from users.
 - A queue. A central hub for passing messages. It should use the same
   implementation as that of the Compute Service (typically RabbitMQ).
 
-==============================
+Install and Configure Prerequisites
-Install the Bare Metal Service
+===================================
-==============================
 
-The Bare Metal Service is a collection of components that provides support
+The Bare Metal Service is a collection of components that provides support to
-to manage and
+manage and provision physical machines. You can configure these components to
-provision physical machines. You can configure these components to run on
+run on separate nodes or the same node. In this guide, the components run on
-separate nodes or the same node. In this guide, the components run on one node,
+one node, typically the Compute Service's compute node.
-typically the Compute Service's compute node.
 
 This section shows you how to install and configure the components.
 
@@ -93,14 +99,13 @@ MySQL database that is used by other OpenStack services.
 Install the Bare Metal Service
 ------------------------------
 
-#. Install these packages::
+#. Install from packages::
 
     # Available in Ubuntu 14.04 (trusty)
     apt-get install ironic-api ironic-conductor python-ironicclient
 
-
 Configure the Bare Metal Service
---------------------------------
+================================
 
 The Bare Metal Service is configured via its configuration file. This file
 is typically located at ``/etc/ironic/ironic.conf``.
@@ -114,8 +119,7 @@ configured for your needs.
 
    Configure the location of the database via the ``connection`` option. In the
    following, replace IRONIC_DBPASSWORD with the password of your ``ironic``
-   user, and replace
+   user, and replace DB_IP with the IP address where the DB server is located::
-   DB_IP with the IP address where the DB server is located::
 
     [database]
     ...
@@ -239,11 +243,10 @@ configured for your needs.
 
 
 Configure Compute Service to use the Bare Metal Service
--------------------------------------------------------
+=======================================================
 
 The Compute Service needs to be configured to use the Bare Metal Service's
-driver.
+driver.  The configuration file for the Compute Service is typically located at
-The configuration file for the Compute Service is typically located at
 ``/etc/nova/nova.conf``. *This configuration file must be modified on the
 Compute Service's controller nodes and compute nodes.*
 
@@ -319,7 +322,7 @@ Compute Service's controller nodes and compute nodes.*
 PXE Setup
 ---------
 
-On the Bare Metal Service node where ``ironic-conductor`` is running,
+On the Bare Metal Service node(s) where ``ironic-conductor`` is running,
 PXE needs to be set up.
 
 #. Make sure these directories exist::

doc/source/deploy/user-guide.rst

@@ -1,3 +1,4 @@
+.. _user-guide:
 
 =======================
 Introduction to Ironic

doc/source/dev/common.rst

@@ -1,5 +1,3 @@
-.. _common:
-
 ============================
 Common Modules and Utilities
 ============================
@@ -8,7 +6,6 @@ Common Modules and Utilities
     ../api/ironic.common.driver_factory
     ../api/ironic.common.exception
     ../api/ironic.common.hash_ring
-    ../api/ironic.common.images
     ../api/ironic.common.states
     ../api/ironic.common.utils
 

doc/source/dev/db.rst

@@ -1,7 +1,7 @@
 .. _db:
 
 ============
-DB API Layer
+Database API
 ============
 
 .. toctree::

doc/source/dev/drivers.rst

@@ -8,12 +8,18 @@ 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.
 
+The SSH driver provides an interface to control the power state of virtual
+machines used in our test environments.
+
+The SeaMicro driver provides an enhanced interface for SeaMicro hardware.
+
 .. toctree::
     ../api/ironic.drivers.base
     ../api/ironic.drivers.pxe
     ../api/ironic.drivers.modules.ipminative
     ../api/ironic.drivers.modules.ipmitool
     ../api/ironic.drivers.modules.pxe
+    ../api/ironic.drivers.modules.seamicro
     ../api/ironic.drivers.modules.ssh
 
 .. _ipmitool: http://ipmitool.sourceforge.net/

doc/source/index.rst

@@ -16,68 +16,43 @@ VM, and so on), then Ironic may be thought of as a *hypervisor API* gluing
 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
+Ironic should be considered Beta quality as of the Icehouse release, and will
-:doc:`dev/architecture` page.
+make the best effort to maintain backwards compatibility from this point
+forward. Release notes are available here:
+https://wiki.openstack.org/wiki/Ironic/ReleaseNotes/Icehouse
 
+The developer documentation provided here is continually kept up-to-date based
+on the latest code, and may not represent the state of our APIs at any given
+release.
 
-Status: Alpha Quality
+Developer Guide
-=====================
+===============
 
-Ironic is targeting inclusion in the OpenStack Icehouse release. The current
+Introduction
-codebase should be considered "alpha" quality. All major functional components
+------------
-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
-.. - configuration
-..   - DB and AMQP
-..   - API and Conductor services
-..   - integration with other OS services
-..   - any driver-specific configuration
-.. - hardware enrollment
-..   - manual vs automatic
-..   - hw plugins
-
-
-Developer Documentation
-=======================
-
-Overview
---------
 
 .. toctree::
   :maxdepth: 1
 
   dev/architecture
   dev/contributing
+
+.. toctree::
   dev/dev-quickstart
 
-Client API Reference
+API References
---------------------
+--------------
 
 .. toctree::
   :maxdepth: 1
 
   webapi/v1
-
-Python API Quick Reference
---------------------------
-
-.. toctree::
-  :maxdepth: 1
-
-  dev/api
   dev/common
   dev/db
   dev/drivers
-  dev/conductor
 
 Admin Guide
-=======================
+===========
 
 Overview
 ----------
@@ -85,15 +60,8 @@ Overview
 .. toctree::
   :maxdepth: 1
 
-  deploy/userguide
+  deploy/user-guide
-
+  deploy/install-guide
-Install Guide
--------------
-
-.. toctree::
-  :maxdepth: 1
-
-  install/ironic-install
 
 Indices and tables
 ==================
@@ -101,6 +69,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
-
-.. _Baremetal Driver: https://wiki.openstack.org/wiki/Baremetal

doc/source/webapi/v1.rst

@@ -1,6 +1,6 @@
-============
+=====================
- V1 Web API
+ RESTful Web API (v1)
-============
+=====================
 
 Chassis
 =======