Open Stack

Excerpts from Markus Zoeller's message of 2016-03-02 18:45:45 +0100:

[a lot snipped]

> Appendix
> ========
> 
> Example of the help text improvement
> -----------------------------------
> As an example, compare the previous documentation of the scheduler 
> option "scheduler_tracks_instance_changes". 
> Before we started:
> 
>     # Determines if the Scheduler tracks changes to instances to help 
>     # with its filtering decisions. (boolean value)
>     #scheduler_tracks_instance_changes = true
> 
> After the improvement:
> 
>     # The scheduler may need information about the instances on a host 
>     # in order to evaluate its filters and weighers. The most common 
>     # need for this information is for the (anti-)affinity filters, 
>     # which need to choose a host based on the instances already running
>     # on a host.
>     #
>     # If the configured filters and weighers do not need this information,
>     # disabling this option will improve performance. It may also be 
>     # disabled when the tracking overhead proves too heavy, although 
>     # this will cause classes requiring host usage data to query the 
>     # database on each request instead.
>     #
>     # This option is only used by the FilterScheduler and its subclasses;
>     # if you use a different scheduler, this option has no effect.
>     #
>     # * Services that use this:
>     #
>     #     ``nova-scheduler``
>     #
>     # * Related options:
>     #
>     #     None
>     #  (boolean value)
>     #scheduler_tracks_instance_changes = true

If, in the course of adding this information, you think it would be
useful for oslo.config or the config generator to provide a way to
expose or derive the information, let me know. We're going to be doing
some more work on the config generator to enable some automation in the
config reference guide maintained by the docs team, and this looks like
the sort of thing that might be useful to include in a discoverable way
(not just within the comment text for the options).

Doug