Open Stack

Hi Docs Team,

I recently removed some deprecated options from Oslo logging and opened
documentation bugs to have these removed.
I was able to get back to debugging why I was unable to generate the tables
myself and have raised some reviews of my observations for getting it
working.

There are two observations that I've noticed today and so I've created
appropriate reviews. [1] and [2]

NOTE: These change the format of output produced, and so they are just my
observations that I hope can lead to further discussion.
As we are near Mitaka release I am not expecting these to be included. As
I'm not involved with the docs team I wanted to fully explain these
proposed changes for feedback.

1. Descriptive Types

I had noticed previously in the configuration reference the use of BoolOpt,
StrOpt, IntOpt etc. Rather non friendly IMO.
I've taken to converting this to more end user readable types such as
Boolean, String, Integer etc.

2. Deprecated Options

When an option is deprecated, it is (optionally) marked with an attribute
deprecated_for_removal, and optionally provided a deprecated_reason.
There is also a inconsistent convention of adding DEPRECATED to the prefix
of the help text.  I suspect the reason why is for documentation purposes.
However if this is not added options that are deprecated may not be clearly
identified this way.
I've provided a means to prefix help with DEPRECATED if the option is
marked for deprecation and this text is not in the help message. I have
also suffixed the option help if this includes a deprecated reason.

To highlight the impact, I use cinder as an example.

Presently two options, enable_v1_api, and enable_v2_api prefix the help
with DEPRECATED.
With my proposed change there are now the following additional options
prefixed DEPRECATED. I've verified the code to be sure.

In the API table, secure_proxy_ssl_header (from oslo.middleware) [3]
In the flashsystem table, flashsystem_multipath_enabled [4]
In the logging table, verbose (from oslo.log) [5]
In the storwize table, storwize_svc_multihostmap_enabled [6]
In the zoning_fabric table, principal_switch_wwn [7]


[1] https://review.openstack.org/#/c/293697/
[2] https://review.openstack.org/#/c/293739/
[3]
http://git.openstack.org/cgit/openstack/oslo.middleware/tree/oslo_middleware/ssl.py#n20
[4]
http://git.openstack.org/cgit/openstack/cinder/tree/cinder/volume/drivers/ibm/flashsystem_fc.py#n49
[5]
http://git.openstack.org/cgit/openstack/oslo.log/tree/oslo_log/_options.py#n44
[6]
http://git.openstack.org/cgit/openstack/cinder/tree/cinder/volume/drivers/ibm/storwize_svc/storwize_svc_common.py#n95
[7]
http://git.openstack.org/cgit/openstack/cinder/tree/cinder/zonemanager/drivers/brocade/brcd_fabric_opts.py#n56

Regards

Ronald
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160316/f8ec6765/attachment.html>