Merge "Configuration documentation migrated"

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>
+   Enabling Drivers <drivers>
-  gmr
+   Ironic Python Agent <drivers/ipa>
-  Upgrade Guide <upgrade-guide>
+   Node Hardware Inspection <inspection>
-  upgrade-to-hardware-types
+   Node Cleaning <cleaning>
-  Release Notes <http://docs.openstack.org/releasenotes/ironic/>
+   Node Adoption <adoption>
-  Troubleshooting FAQ <troubleshooting>
+   RAID Configuration <raid>
-
-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>
+   Multi-tenant Networking <multitenancy>
-  Adopting Nodes in an ACTIVE state <adoption>
+   Port Groups <portgroups>
-  Configuring for Multi-tenant Networking <multitenancy>
+   Configuring Web or Serial Console <console>
-  Configuring for port groups <portgroups>
+   Enabling Notifications <notifications>
-  Configuring node web or serial console <console>
+   Ceph Object Gateway <radosgw>
-  Emitting software metrics <metrics>
+   Emitting Software Metrics <metrics>
    Auditing API Traffic <api-audit-support>
-  Notifications <notifications>
+   Service State Reporting <gmr>
-  Ceph Object Gateway support <radosgw>
+   Upgrade Guide <upgrade-guide>
-  /configuration/sample-config
+   Security <security>
-  /configuration/sample-policy
+   Troubleshooting FAQ <troubleshooting>
 
 Dashboard Integration
 ---------------------

doc/source/admin/upgrade-guide.rst

@@ -320,6 +320,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
 ==============================

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',
               ]
 

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

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
+  Configuration Options <config>
-  sample-policy
+  Sample Config File <sample-config>
+  Policies <policy>
+  Sample Policy File <sample-policy>

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

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
+The following is a sample Ironic configuration for adaptation and use. For a
-auto-generated from Ironic when this documentation is built, so
+detailed overview of all available configuration options, refer to
-if you find issues with an option, please compare your version of
+:doc:`config`.
-Ironic with the version of this documentation.
 
-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

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
 https://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
 ==================
 

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

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