Reorganize mogan docs

This make the docs index more clear, and change some content.

Change-Id: If6ab60017fc3ffec3836a4da27d6453fb0c0b4a4

doc/source/index.rst

@@ -15,34 +15,59 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-===========================================
-Welcome to Mogan's developer documentation!
-===========================================
+====================================
+OpenStack Bare Metal Compute (mogan)
+====================================
 
 Introduction
 ============
 
-Mogan is an OpenStack project dedicated for bare metal computing management,
-which is designed specifically for bare metals, so compared with Nova, we can
-provide a more lightweight and convenient platform with more advanced features
-by leveraging Ironic. Besides this, we also plan to support RSD, then we can
-not only provide Pre-set Configuration Servers, but also Custom Servers.
+Mogan is an OpenStack project which offers bare metals as first class
+resources to users, supporting variety of bare metal provisioning drivers
+including Ironic.
 
-Site Notes
-----------
+Installation Guide
+==================
 
-This site is primarily intended to provide documentation for developers
-interested in contributing to or working with mogan. It *also* contains
-references and guides for administrators which are not yet hosted elsewhere on
-the OpenStack documentation sites.
+.. toctree::
+  :maxdepth: 1
+
+  installation/configure-mogan-api-uwsgi
+  installation/build-user-images
 
 
-Developer's Guide
+User Guide
+==========
+
+.. toctree::
+  :maxdepth: 1
+
+  user/states
+  user/root-disk-partitions
+
+
+Administrator Guide
+===================
+
+.. toctree::
+  :maxdepth: 1
+
+  admin/gmr
+
+
+Configuration Guide
+===================
+
+.. toctree::
+  :maxdepth: 1
+
+  configuration/sample_config
+  configuration/sample_policy
+
+
+Contributor Guide
 =================
 
-Getting Started
----------------
-
 If you are new to mogan, this section contains information that should help
 you get started as a developer working on the project or contributing to the
 project.
@@ -50,54 +75,10 @@ project.
 .. toctree::
   :maxdepth: 1
 
-  Developer Contribution Guide <dev/code-contribution-guide>
-  Setting Up Your Development Environment <dev/dev-quickstart>
+  contributor/code-contribution-guide
+  contributor/dev-quickstart
+  contributor/testing
 
-The following pages describe the architecture of the service.
-
-.. toctree::
-  :maxdepth: 1
-
-  States and Transitions <states>
-
-Advanced testing and guides
----------------------------
-
-.. toctree::
-    :maxdepth: 1
-
-    dev/gmr
-
-Administrator's Guide
-=====================
-
-Sample Configuration File
--------------------------
-
-.. toctree::
-    :maxdepth: 1
-
-    sample_config
-
-Sample Policy file
-------------------
-
-.. toctree::
-    :maxdepth: 1
-
-    sample_policy
-
-
-User's Guide
-============
-
-Root Disk Partitions
---------------------
-
-.. toctree::
-    :maxdepth: 1
-
-    user/root-disk-partitions
 
 Command References
 ==================
@@ -109,22 +90,6 @@ Here are references for commands not elsewhere documented.
 
   cmds/mogan-dbsync
 
-Running tests of Mogan
-======================
-
-.. toctree::
-   :maxdepth: 1
-
-   dev/testing
-
-Installation and Setup
-======================
-
-.. toctree::
-   :maxdepth: 1
-
-   installation/uwsgi
-   installation/image-requirements
 
 Indices and tables
 ==================

doc/source/installation/build-user-images.rst

@@ -0,0 +1,45 @@
+Build user images
+=================
+
+Mogan bare metal provisioning supports two types of images, partition
+images and whole disk images.
+
+But we only support local boot, so it's important to note that in order
+for this to work, the partition image being deployed with Mogan **must**
+contain ``grub2`` installed within it.
+
+Config Drive
+------------
+
+The configuration drive is used to store server specific metadata.
+``Cloud-init`` has a collection of data source modules, so when building the
+image with `disk-image-builder`_ we have to define ``DIB_CLOUD_INIT_DATASOURCES``
+environment variable and set the appropriate sources to enable the configuration
+drive, for example::
+
+    DIB_CLOUD_INIT_DATASOURCES="ConfigDrive, OpenStack" disk-image-create -o fedora-cloud-image fedora baremetal grub2
+
+For more information see `how to configure cloud-init data sources
+<https://docs.openstack.org/diskimage-builder/latest/elements/cloud-init-datasources/README.html>`_.
+
+Build images with disk-image-builder
+************************************
+
+The `disk-image-builder`_ can be used to create user images required for
+deployment and the actual OS which the user is going to run.
+
+.. _disk-image-builder: https://docs.openstack.org/diskimage-builder/latest/
+
+#. Partition images
+
+   .. code-block:: console
+
+      $ DIB_CLOUD_INIT_DATASOURCES="ConfigDrive, OpenStack" disk-image-create ubuntu baremetal grub2 dhcp-all-interfaces cloud-init-datasources -o my-image
+
+#. Whole disk images
+
+   .. code-block:: console
+
+      $ DIB_CLOUD_INIT_DATASOURCES="ConfigDrive, OpenStack" disk-image-create ubuntu vm dhcp-all-interfaces cloud-init-datasources -o my-image
+
+.. _disk-image-builder: https://docs.openstack.org/diskimage-builder/latest/

doc/source/installation/configure-mogan-api-uwsgi.rst

@@ -15,8 +15,8 @@
       under the License.
 
 
-Running Mogan API using uWSGI
-=============================
+Configure Mogan API with uWSGI
+==============================
 The recommended way to deploy Mogan is have a web server such as Apache
 or nginx to handle http requests and proxy these requests to Mogan WSGI
 app running in uWSGI. Mogan comes with some configuration templates on

doc/source/installation/image-requirements.rst

@@ -1,34 +0,0 @@
-Image requirements
-~~~~~~~~~~~~~~~~~~
-
-Mogan bare metal provisioning supports two types of images, partition
-images and whole disk images. Both of them support only local boot.
-
-It's important to note that in order for this to work, the partition image
-being deployed with Mogan **must** contain ``grub2`` installed within it.
-
-Mogan only support config drive with cloud-init, so the image **must** contain
-configdrive datasource.
-
-Build user images
-~~~~~~~~~~~~~~~~~
-
-This section describes how to build user images which are installed
-on the bare metal server through mogan.
-
-The `disk-image-builder`_ can be used to create user images required for
-deployment and the actual OS which the user is going to run.
-
-.. _disk-image-builder: https://docs.openstack.org/diskimage-builder/latest/
-
-#. Partition images
-
-   .. code-block:: console
-
-      $ DIB_CLOUD_INIT_DATASOURCES="ConfigDrive, OpenStack" disk-image-create ubuntu baremetal grub2 dhcp-all-interfaces cloud-init-datasources -o my-image
-
-#. Whole disk images
-
-   .. code-block:: console
-
-      $ DIB_CLOUD_INIT_DATASOURCES="ConfigDrive, OpenStack" disk-image-create ubuntu vm dhcp-all-interfaces cloud-init-datasources -o my-image