From 353b7f7c9a6221a14f770bd4c9e893a3ddb11ba2 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 11 Mar 2016 15:39:52 -0500 Subject: [PATCH] improve documentation about registering entry points for config generator Change-Id: I166033ca3073325004bacaabcbee729e4cf4f809 Signed-off-by: Doug Hellmann --- doc/source/generator.rst | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/source/generator.rst b/doc/source/generator.rst index c160ffd2..111028b2 100644 --- a/doc/source/generator.rst +++ b/doc/source/generator.rst @@ -87,7 +87,7 @@ values after *all* options are loaded. The hooks are registered in a separate entry point namespace (``oslo.config.opts.defaults``), using the same entry point name as -the application's ``list_opts()`` function. +**the application's** ``list_opts()`` function. :: @@ -95,6 +95,27 @@ the application's ``list_opts()`` function. oslo.config.opts.defaults = keystone = keystone.common.config:update_opt_defaults +.. warning:: + + Never, under any circumstances, register an entry point using a + name owned by another project. Doing so causes unexpected interplay + between projects within the config generator and will result in + failure to generate the configuration file or invalid values + showing in the sample. + + In this case, the name of the entry point for the default override + function *must* match the name of one of the entry points defining + options for the application in order to be detected and + used. Applications that have multple list_opts functions should use + one that is present in the inputs for the config generator where + the changed defaults need to appear. For example, if an application + defines ``foo.api`` to list the API-related options, and needs to + override the defaults in the ``oslo.middleware.cors`` library, the + application should register ``foo.api`` under + ``oslo.config.opts.defaults`` and point to a function within the + application code space that changes the defaults for + ``oslo.middleware.cors``. + The update function should take no arguments. It should invoke the public :func:`set_defaults` functions in any libraries for which it has option defaults to override, just as the application does during