[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

9 files changed, 105 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
diff --git a/tools/trove-config-generator.conf b/tools/trove-config-generator.conf
new file mode 100644
index 00000000..79fc7f28
--- /dev/null
+++ b/tools/trove-config-generator.conf
@@ -0,0 +1,9 @@
+[DEFAULT]
+output_file = etc/trove/trove.conf.sample
+wrap_width = 79
+namespace = trove.config
+namespace = oslo.messaging
+namespace = oslo.middleware
+namespace = oslo.log
+namespace = oslo.policy
+namespace = osprofiler
diff --git a/tox.ini b/tox.ini
index 175a9c94..989abbc5 100644
--- a/tox.ini
+++ b/tox.ini
@@ -88,6 +88,9 @@ commands = bandit -r trove -n5 -x tests
 envdir = {toxworkdir}/bandit
 commands = bandit-baseline -r trove -n5 -x tests -ii -ll
 
+[testenv:genconfig]
+commands = oslo-config-generator --config-file=tools/trove-config-generator.conf
+
 [testenv:genpolicy]
 commands = oslopolicy-sample-generator --config-file=tools/trove-policy-generator.conf
 
diff --git a/trove/common/cfg.py b/trove/common/cfg.py
index a490b431..e3f66f30 100644
--- a/trove/common/cfg.py
+++ b/trove/common/cfg.py
@@ -1574,6 +1574,7 @@ def list_opts():
         (None, path_opts + versions_opts + common_opts),
         ('database', database_opts),
         (mysql_group, mysql_opts),
+        (postgresql_group, postgresql_opts),
         (mariadb_group, mariadb_opts),
         (network_group, network_opts),
         (service_credentials_group, service_credentials_opts),