Allow a markup syntax to structure the help text of an option

Registered by Markus Zoeller (markus_z) on 2015-08-28

The help text of a config option could be made more readable and
easier to understand if it could be structured with a markup language.
The Linux Documentation Project uses "DocBook" to do this [1], but
as we seem to mainly use ReStructuredText (ReST) in project specs
and our documentation team also transfers the manuals from DocBook to
ReST, we could use it in the help text too.

An example
----------

The option "notify_on_state_change" is displayed as plain continuous
text :

    (StrOpt) If set, send compute.instance.update notifications on
    instance state changes. Valid values are None for no notifications,
    "vm_state" for notifications on VM state changes, or
    "vm_and_task_state" for notifications on VM and task state changes.

and could be changed to:

    (StrOpt) If set, send `compute.instance.update` notifications on
    instance state changes. Valid values are:

    * `None` for no notifications,
    * `vm_state` for notifications on VM state changes, or
    * `vm_and_task_state` for notifications on VM and task state changes.

The parts of the text which are code or values could be clarified and
the valid values could be displayed as bullet list.

Projects like the OpenStack manuals could generate a text which more
readable by using this. The users should be able to clarify that they
use a markup, for example by declaring it in the construction of the
option:

        cfg.StrOpt('notify_on_state_change',
        help='If set, send `compute.instance.update` notifications '
             'on instance state changes. Valid values are:'
             ''
             '* `None` for no notifications, '
             '* `vm_state` for notifications on VM state changes, or '
             '* `vm_and_task_state` for notifications on VM and task '
             ' state changes.',
        markup="rst"

The default value of "markup" should be "txt" to be backwards
compatible. If [2] gets approved, the markup could be extended to be
used on that information too.

References
----------
[1] http://www.tldp.org/LDP/LDP-Author-Guide/html/index.html
[2] https://blueprints.launchpad.net/oslo.config/+spec/option-interdependencies

Blueprint information

Status:
Not started
Approver:
None
Priority:
Undefined
Drafter:
Markus Zoeller (markus_z)
Direction:
Needs approval
Assignee:
None
Definition:
Pending Approval
Series goal:
None
Implementation:
Unknown
Milestone target:
None

Related branches

Sprints

Whiteboard

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.