[doc-migration] Add configuration folder for documentation

This patch does the following:
* Adds a configuration folder to contain automated generated config
files for Ironic.
* Adds `oslo_config.sphinxconfiggen` to the extensions list.
* Adds `oslo_policy.sphinxpolicygen` to the extensions list.
* Adds ironic-policy-generator.conf

This is important for Ironic to be included in the list of services
on https://docs.openstack.org/pike/configuration/

Change-Id: I51a7204ce00be2588e427c1951e8be7dc7a22647
Closes-bug: #1706176

.gitignore

@@ -7,6 +7,7 @@
 # Sphinx
 _build
 doc/source/contributor/api/
+_static/ironic
 
 # release notes build
 releasenotes/build

doc/source/admin/index.rst

@@ -39,9 +39,8 @@ of ironic that may or may not be suitable to every situation.
   Auditing API Traffic <api-audit-support>
   Notifications <notifications>
   Ceph Object Gateway support <radosgw>
-  Configuration Reference <http://docs.openstack.org/draft/config-reference/bare-metal.html>
-  Sample configuration file <https://git.openstack.org/cgit/openstack/ironic/tree/etc/ironic/ironic.conf.sample>
-
+  /configuration/sample-config
+  /configuration/sample-policy
 
 Dashboard Integration
 ---------------------

doc/source/conf.py

@@ -21,6 +21,8 @@ extensions = ['sphinx.ext.autodoc',
               'sphinxcontrib.pecanwsme.rest',
               'sphinxcontrib.seqdiag',
               'wsmeext.sphinxext',
+              'oslo_config.sphinxconfiggen',
+              'oslo_policy.sphinxpolicygen',
               ]
 
 try:
@@ -53,6 +55,12 @@ master_doc = 'index'
 project = u'Ironic'
 copyright = u'OpenStack Foundation'
 
+config_generator_config_file = '../../tools/config/ironic-config-generator.conf'
+sample_config_basename = '_static/ironic'
+
+policy_generator_config_file = '../../tools/policy/ironic-policy-generator.conf'
+sample_policy_basename = '_static/ironic'
+
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.

doc/source/configuration/index.rst

@@ -0,0 +1,10 @@
+Configuration Guide
+-------------------
+
+Here are sample configuration files generated automatically for Ironic.
+
+.. toctree::
+  :maxdepth: 1
+
+  sample-config
+  sample-policy

doc/source/configuration/sample-config.rst

@@ -0,0 +1,13 @@
+============================
+Ironic Configuration Options
+============================
+
+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 sample configuration can also be downloaded as a :download:`file
+</_static/ironic.conf.sample>`.
+
+.. literalinclude:: /_static/ironic.conf.sample

doc/source/configuration/sample-policy.rst

@@ -0,0 +1,12 @@
+=============
+Ironic Policy
+=============
+
+The following is a sample Ironic policy file, autogenerated from Ironic when
+this documentation is built. To prevent conflicts, ensure your version of
+Ironic aligns with the version of this documentation.
+
+The sample policy can also be downloaded as a :download:`file
+</_static/ironic.policy.yaml.sample>`.
+
+.. literalinclude:: /_static/ironic.policy.yaml.sample

doc/source/index.rst

@@ -38,6 +38,14 @@ Administrator Guide
 
   admin/index
 
+Configuration Reference
+=======================
+
+.. toctree::
+  :maxdepth: 2
+
+  configuration/index
+
 Driver References
 =================
 

tools/policy/ironic-policy-generator.conf

@@ -0,0 +1,3 @@
+[DEFAULT]
+output_file = etc/ironic/policy.json.sample
+namespace = ironic.api

tox.ini

@@ -65,7 +65,7 @@ commands =
 sitepackages = False
 envdir = {toxworkdir}/venv
 commands =
-  oslopolicy-sample-generator --namespace=ironic.api --output-file=etc/ironic/policy.json.sample
+  oslopolicy-sample-generator --config-file=tools/policy/ironic-policy-generator.conf
 
 [testenv:debug]
 commands = oslo_debug_helper -t ironic/tests/unit {posargs}