Configuration documentation migrated

Documentation layout aligned with the OS standards.

The admin page cleaned up - unrelated references moved
elsewhere linking merely admin pages.

The configuration page refactored, ironic.conf
and policy.conf documentation and samples
automatically generated by oslo_config.sphinxext.

Change-Id: I9075e2688f59ecd8ab5c489679f2c53d6294f28d
(cherry picked from commit af8f46b7f4fc62aa8802a449d04325a0d7e79ace)

10 files changed, 96 insertions, 67 deletions

diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 3697e4649..af4d39c14 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -1,48 +1,31 @@
 Administrator's Guide
 =====================
 
-Installation & Operations
--------------------------
-
 If you are a system administrator running Ironic, this section contains
-information that should help you understand how to deploy, operate, and upgrade
+information that may help you understand how to operate and upgrade
 the services.
 
 .. toctree::
   :maxdepth: 1
 
-  Installation Guide </install/index>
-  gmr
-  Upgrade Guide <upgrade-guide>
-  upgrade-to-hardware-types
-  Release Notes <http://docs.openstack.org/releasenotes/ironic/>
-  Troubleshooting FAQ <troubleshooting>
-
-Configuration
--------------
-
-There are many aspects of the Bare Metal service which are environment
-specific. The following pages will be helpful in configuring specific aspects
-of ironic that may or may not be suitable to every situation.
-
-.. toctree::
-  :maxdepth: 1
-
-  Guide to Node Cleaning <cleaning>
-  Configuring Node Inspection <inspection>
-  Configuring RAID during deployment <raid>
-  Configuring to boot from volume <boot-from-volume>
-  Security considerations for your Bare Metal installation <security>
-  Adopting Nodes in an ACTIVE state <adoption>
-  Configuring for Multi-tenant Networking <multitenancy>
-  Configuring for port groups <portgroups>
-  Configuring node web or serial console <console>
-  Emitting software metrics <metrics>
-  Auditing API Traffic <api-audit-support>
-  Notifications <notifications>
-  Ceph Object Gateway support <radosgw>
-  /configuration/sample-config
-  /configuration/sample-policy
+   Enabling Drivers <drivers>
+   Ironic Python Agent <drivers/ipa>
+   Node Hardware Inspection <inspection>
+   Node Cleaning <cleaning>
+   Node Adoption <adoption>
+   RAID Configuration <raid>
+   Configuring to boot from volume <boot-from-volume>
+   Multi-tenant Networking <multitenancy>
+   Port Groups <portgroups>
+   Configuring Web or Serial Console <console>
+   Enabling Notifications <notifications>
+   Ceph Object Gateway <radosgw>
+   Emitting Software Metrics <metrics>
+   Auditing API Traffic <api-audit-support>
+   Service State Reporting <gmr>
+   Upgrade Guide <upgrade-guide>
+   Security <security>
+   Troubleshooting FAQ <troubleshooting>
 
 Dashboard Integration
 ---------------------
diff --git a/doc/source/admin/upgrade-guide.rst b/doc/source/admin/upgrade-guide.rst
index 7441e7ae9..050e796ca 100644
--- a/doc/source/admin/upgrade-guide.rst
+++ b/doc/source/admin/upgrade-guide.rst
@@ -321,6 +321,11 @@ Upgrading from Ocata to Pike
 Other upgrade instructions are in the `Pike release notes
 <https://docs.openstack.org/releasenotes/ironic/pike.html>`_.
 
+.. toctree::
+  :maxdepth: 1
+
+  upgrade-to-hardware-types.rst
+
 
 Upgrading from Newton to Ocata
 ==============================
diff --git a/doc/source/conf.py b/doc/source/conf.py
index ed96dd3a5..5436dd77a 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -21,7 +21,9 @@ extensions = ['sphinx.ext.autodoc',
               'sphinxcontrib.pecanwsme.rest',
               'sphinxcontrib.seqdiag',
               'wsmeext.sphinxext',
+              'oslo_config.sphinxext',
               'oslo_config.sphinxconfiggen',
+              'oslo_policy.sphinxext',
               'oslo_policy.sphinxpolicygen',
               ]
 
diff --git a/doc/source/configuration/config.rst b/doc/source/configuration/config.rst
new file mode 100644
index 000000000..6b8a5c7cc
--- /dev/null
+++ b/doc/source/configuration/config.rst
@@ -0,0 +1,10 @@
+=====================
+Configuration Options
+=====================
+
+The following is an overview of all available configuration options in
+Ironic. For a sample configuration file, refer to
+:doc:`sample-config`.
+
+.. show-options::
+   :config-file: tools/config/ironic-config-generator.conf
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index 3d3f449eb..a21f4e558 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,10 +1,16 @@
-Configuration Guide
--------------------
+=======================
+Configuration Reference
+=======================
 
-Here are sample configuration files generated automatically for Ironic.
+Many aspects of the Bare Metal service are specific to the environment
+it is deployed in. The following pages describe configuration
+options that can be used to adjust the service to your particular
+situation.
 
 .. toctree::
   :maxdepth: 1
 
-  sample-config
-  sample-policy
+  Configuration Options <config>
+  Sample Config File <sample-config>
+  Policies <policy>
+  Sample Policy File <sample-policy>
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
new file mode 100644
index 000000000..251e45c22
--- /dev/null
+++ b/doc/source/configuration/policy.rst
@@ -0,0 +1,9 @@
+========
+Policies
+========
+
+The following is an overview of all available policies in Ironic.  For
+a sample configuration file, refer to :doc:`sample-policy`.
+
+.. show-policy::
+   :config-file: tools/policy/ironic-policy-generator.conf
diff --git a/doc/source/configuration/sample-config.rst b/doc/source/configuration/sample-config.rst
index afee14941..cfb8980fb 100644
--- a/doc/source/configuration/sample-config.rst
+++ b/doc/source/configuration/sample-config.rst
@@ -1,13 +1,18 @@
-============================
-Ironic Configuration Options
-============================
+=========================
+Sample Configuration File
+=========================
 
-The following is a sample Ironic configuration for adaptation and use. It is
-auto-generated from Ironic when this documentation is built, so
-if you find issues with an option, please compare your version of
-Ironic with the version of this documentation.
+The following is a sample Ironic configuration for adaptation and use. For a
+detailed overview of all available configuration options, refer to
+:doc:`config`.
 
-The sample configuration can also be downloaded as a :download:`file
+The sample configuration can also be viewed in :download:`file form
 </_static/ironic.conf.sample>`.
 
+.. important::
+
+   The sample configuration file is auto-generated from Ironic when this
+   documentation is built. You must ensure your version of Ironic matches the
+   version of this documentation.
+
 .. literalinclude:: /_static/ironic.conf.sample
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4214b7883..77ed29f26 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -22,6 +22,22 @@ previous release of ironic, append the OpenStack release name to the URL; for
 example, the ``ocata`` release is available at
 http://docs.openstack.org/ironic/ocata/.
 
+Installation Guide
+==================
+
+.. toctree::
+  :maxdepth: 2
+
+  install/index
+
+Upgrade Guide
+=============
+
+.. toctree::
+  :maxdepth: 2
+
+  admin/upgrade-guide
+
 User Guide
 ==========
 
@@ -38,26 +54,14 @@ Administrator Guide
 
   admin/index
 
-Configuration Reference
-=======================
+Configuration Guide
+===================
 
 .. toctree::
   :maxdepth: 2
 
   configuration/index
 
-Driver References
-=================
-
-Every driver author is expected to document the use and configuration of their
-driver. These pages are linked below.
-
-.. toctree::
-  :maxdepth: 1
-
-  Driver Documentation pages <admin/drivers>
-  Further Considerations for the Agent Drivers <admin/drivers/ipa>
-
 Bare Metal API References
 =========================
 
@@ -90,6 +94,11 @@ Contributor Guide
 
    contributor/index
 
+Release Notes
+=============
+
+`Release Notes <http://docs.openstack.org/releasenotes/ironic/>`_
+
 Indices and tables
 ==================
 
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
index c32955ad5..e88737032 100644
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@@ -1,5 +1,5 @@
 =====================================
-Bare Metal service installation guide
+Bare Metal Service Installation Guide
 =====================================
 
 The Bare Metal service is a collection of components that provides support to
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index d2650ade5..8697235d5 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -1,8 +1,8 @@
 .. _user-guide:
 
-======================
-Introduction to Ironic
-======================
+=============================
+Bare Metal Service User Guide
+=============================
 
 Ironic is an OpenStack project which provisions bare metal (as opposed to
 virtual) machines. It may be used independently or as part of an OpenStack