Merge "Add docs for configuration options"

TODO.rst

@@ -18,12 +18,6 @@ API
   - Validate API request for unexpected attributes. Such attributes should
     result in a 400 error. [https://review.openstack.org/#/c/260292]
 
-DOC
----
-  - Add documentation for configuration options, configuration in the project
-    oslo.messaging project can be used as an example. E.g. the
-    `oslo_config.sphinxext` extension and the `show-options` stanza.
-
 ENGINE
 ------
   - Scaling Improvments [https://etherpad.openstack.org/p/newton-senlin-ha]

doc/source/conf.py

@@ -28,7 +28,8 @@ extensions = [
     # 'sphinx.ext.todo'
     'sphinx.ext.graphviz',
     'sphinx.ext.intersphinx',
-    'oslosphinx'
+    'oslosphinx',
+    'oslo_config.sphinxext',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy

doc/source/configuration.rst

@@ -0,0 +1,16 @@
+=======================
+ Configuration Options
+=======================
+
+senlin uses `oslo.config` to define and manage configuration options to
+allow the deployer to control many aspects of the service API and the service
+engine.
+
+.. show-options:: senlin.config
+
+Options
+=======
+
+.. currentmodule:: senlin.common.config
+
+.. autofunction:: list_opts

doc/source/index.rst

@@ -27,6 +27,7 @@ contribute to the project.
 
    overview
    install
+   configuration
    tutorial/index
    user/index
    developer/index

doc/source/install.rst

@@ -115,6 +115,13 @@ The most common options to be customized include:
   rabbit_hosts = <HOST>
   rabbit_password = <RABBIT PASSWORD>
 
+  [oslo_messaging_notifications]
+  driver = messaging
+
+For more comprehensive helps on configuration options, please refer to
+:doc:`Configuration Options <configuration>` documentation.
+
+
 5. Create Senlin Database.
 
  Create Senlin database using the :command:`senlin-db-recreate` script under

releasenotes/notes/config-doc-cb8b37e360422301.yaml

@@ -0,0 +1,4 @@
+---
+other:
+  - Senlin API/Engine configuration options are now documented and published
+    online.

senlin/common/config.py

@@ -160,6 +160,23 @@ cfg.CONF.register_opts(webhook_opts, group=webhook_group)
 
 
 def list_opts():
+    """Return a list of oslo.config options available.
+
+    The purpose of this function is to allow tools like the Oslo sample config
+    file generator to discover the options exposed to users by this service.
+    The returned list includes all oslo.config options which may be registered
+    at runtime by the service api/engine.
+
+    Each element of the list is a tuple. The first element is the name of the
+    group under which the list of elements in the second element will be
+    registered. A group name of None corresponds to the [DEFAULT] group in
+    config files.
+
+    This function is also discoverable via the 'senlin.config' entry point
+    under the 'oslo.config.opts' namespace.
+
+    :returns: a list of (group_name, opts) tuples
+    """
     for g, o in wsgi.wsgi_opts():
         yield g, o
     yield None, cloud_backend_opts

setup.cfg

@@ -30,7 +30,7 @@ console_scripts =
     senlin-manage = senlin.cmd.manage:main
 
 oslo.config.opts =
-    senlin.common.config = senlin.common.config:list_opts
+    senlin.config = senlin.common.config:list_opts
 
 senlin.profiles =
     os.heat.stack-1.0 = senlin.profiles.os.heat.stack:StackProfile