4 files changed, 43 insertions, 13 deletions
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