doc: Populate the 'configuration' section

Per the spec [1]:
    configuration/ – automatically generated configuration reference
    information based on oslo.config’s sphinx integration (or manually
    written for projects not using oslo.config). Step-by-step guides for
    doing things like enabling cells or configuring a specific driver
    should be placed in the admin/ section.

Only the sample_config file fit into this category at present.
Let's add new sample_config file and move the configuration section to
this category.

Change-Id: I789fe53f4df9409dd6e4a6d5f9280feb65792258
Implements: blueprint designate-doc-migration
Partial-Bug: #1706173

doc/source/conf.py

@@ -32,7 +32,8 @@ extensions = ['sphinx.ext.autodoc',
               'sphinxcontrib.httpdomain',
               'ext.support_matrix',
               'ext.custom_css',
-              'openstackdocstheme']
+              'openstackdocstheme',
+              'oslo_config.sphinxconfiggen']
 
 # openstackdocstheme options
 repository_name = 'openstack/designate'
@@ -40,6 +41,9 @@ bug_project = 'designate'
 bug_tag = ''
 html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
+config_generator_config_file = '../../etc/designate/designate-config-generator.conf'
+sample_config_basename = '_static/designate'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/source/configuration/index.rst

@@ -0,0 +1,47 @@
+..
+      Copyright 2011 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _configuration:
+
+Designate Configuration Guide
+=============================
+
+Designate configuration is needed for getting it work correctly
+either with real OpenStack environment or without OpenStack environment.
+
+**NOTE:** The most of the following operations should performed in designate
+directory.
+
+.. index::
+    double: configure; designate
+
+#. Create the designate.conf file
+
+    ::
+
+      $ editor designate.conf
+
+#. Copy or mirror the configuration from this sample file here:
+
+    .. literalinclude:: ../examples/basic-config-sample.conf
+        :language: ini
+
+#. You can generate full sample *designate.conf* (if it does not already exist)::
+
+    $ oslo-config-generator --config-file etc/designate/designate-config-generator.conf --output-file /etc/designate/designate.conf
+
+.. literalinclude:: ../_static/designate.conf.sample
+    :language: ini

doc/source/contributor/ubuntu-dev.rst

@@ -116,20 +116,7 @@ Installing Designate
 Configuring Designate
 ======================
 
-.. index::
+Refer to :ref:`configuration` for a sample configuration options.
-    double: configure; designate
-
-Create the designate.conf file
-
-::
-
-  $ editor designate.conf
-
-
-Copy or mirror the configuration from this sample file here:
-
-.. literalinclude:: ../examples/basic-config-sample.conf
-    :language: ini
 
 
 Installing RabbitMQ

doc/source/index.rst

@@ -22,6 +22,7 @@ Contents
     contributor/index
     user/index
     admin/index
+    configuration/index
 
 This documentation is generated by the Sphinx toolkit and lives in the
 `source tree <https://git.openstack.org/cgit/openstack/designate>`_.