[doc] Add configuration reference

Config reference has been dropped for some reason several releases before.
We return configuration reference along with policy to the docs.

Change-Id: I0927466d18eca5572932fcf9e2ca6349b11ca847

6 files changed, 92 insertions, 3 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index fbbd02cc..bde81cf1 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -14,9 +14,16 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.todo',
-              'sphinx.ext.viewcode',
-              'openstackdocstheme',
-              'stevedore.sphinxext']
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+    'openstackdocstheme',
+    'stevedore.sphinxext',
+    'oslo_config.sphinxconfiggen',
+    'oslo_config.sphinxext',
+    'oslo_policy.sphinxpolicygen',
+    'oslo_policy.sphinxext',
+]
 
 # openstackdocstheme options
 openstackdocs_repo_name = 'openstack/trove'
@@ -25,6 +32,15 @@ openstack_auto_name = False
 openstackdocs_bug_tag = ''
 html_theme = 'openstackdocs'
 
+# sphinxcontrib.apidoc options
+config_generator_config_file = (
+    '../../tools/trove-config-generator.conf')
+sample_config_basename = '_static/trove'
+
+policy_generator_config_file = (
+    '../../tools/trove-policy-generator.conf')
+sample_policy_basename = '_static/trove'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/doc/source/reference/conf-file.rst b/doc/source/reference/conf-file.rst
new file mode 100644
index 00000000..9b8dd2f8
--- /dev/null
+++ b/doc/source/reference/conf-file.rst
@@ -0,0 +1,24 @@
+.. _trove-config-file:
+
+-------------------------------
+Trove Sample Configuration File
+-------------------------------
+
+Configure Trove by editing /etc/trove/trove.conf.
+
+No config file is provided with the source code, it will be created during
+the installation. In case where no configuration file was installed, one
+can be easily created by running::
+
+    tox -e genconfig
+
+
+To see configuration options available, please refer to :ref:`trove-conf`.
+
+.. only:: html
+
+   The following is a sample Trove configuration for adaptation and use.
+   It is auto-generated from Trove when this documentation is built, and
+   can also be viewed in `file form <../_static/trove.conf.sample>`_.
+
+   .. literalinclude:: ../_static/trove.conf.sample
diff --git a/doc/source/reference/conf.rst b/doc/source/reference/conf.rst
new file mode 100644
index 00000000..7aeecf07
--- /dev/null
+++ b/doc/source/reference/conf.rst
@@ -0,0 +1,11 @@
+.. _trove-conf:
+
+---------------------------
+Trove Configuration Options
+---------------------------
+
+The following is an overview of all available configuration options in Trove.
+To see sample configuration file, see :ref:`trove-config-file`.
+
+.. show-options::
+   :config-file: tools/trove-config-generator.conf
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 862b64e0..14bfb911 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -6,4 +6,8 @@
    :maxdepth: 1
 
    notifier.rst
+   conf.rst
+   conf-file.rst
+   policy.rst
+   policy-file.rst
    trove_api_extensions.rst
diff --git a/doc/source/reference/policy-file.rst b/doc/source/reference/policy-file.rst
new file mode 100644
index 00000000..7b3157f2
--- /dev/null
+++ b/doc/source/reference/policy-file.rst
@@ -0,0 +1,20 @@
+.. _trove-policy-file:
+
+===========
+policy.yaml
+===========
+
+.. warning::
+
+   JSON formatted policy file is deprecated since Trove 15.0.0 (Wallaby).
+   This `oslopolicy-convert-json-to-yaml`__ tool will migrate your existing
+   JSON-formatted policy file to YAML in a backward-compatible way.
+
+.. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html
+
+To see available policies, refer to :ref:`policy-configuration`.
+
+Use the ``policy.yaml`` file to define additional access controls that will be
+applied to Trove:
+
+.. literalinclude:: ../_static/trove.policy.yaml.sample
diff --git a/doc/source/reference/policy.rst b/doc/source/reference/policy.rst
new file mode 100644
index 00000000..ece2beac
--- /dev/null
+++ b/doc/source/reference/policy.rst
@@ -0,0 +1,14 @@
+.. _policy-configuration:
+
+--------------------------
+Trove Policy Configuration
+--------------------------
+
+The following is an overview of all available policies in Aodh.
+
+For a sample policy file refer to the :ref:`trove-policy-file` or
+run ``tox -egenpolicy`` in the repo folder and the new file will
+be located in etc/trove/policy.yaml.sample
+
+.. show-policy::
+   :config-file: tools/trove-policy-generator.conf