<div dir="ltr"><div><div class="gmail_signature"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><div><div><div>Hi Docs Team,</div></div></div></div><div><br></div><div>I recently removed some deprecated options from Oslo logging and opened documentation bugs to have these removed.</div><div>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.</div><div><br></div><div>There are two observations that I've noticed today and so I've created appropriate reviews. [1] and [2]</div><div><br></div><div>NOTE: These change the format of output produced, and so they are just my observations that I hope can lead to further discussion. </div><div>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.</div><div><br></div><div>1. Descriptive Types</div><div><br></div><div>I had noticed previously in the configuration reference the use of BoolOpt, StrOpt, IntOpt etc. Rather non friendly IMO.</div><div>I've taken to converting this to more end user readable types such as Boolean, String, Integer etc.</div><div><br></div><div>2. Deprecated Options</div><div><br></div><div>When an option is deprecated, it is (optionally) marked with an attribute deprecated_for_removal, and optionally provided a deprecated_reason. </div><div>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.</div><div>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.</div><div><br></div><div>To highlight the impact, I use cinder as an example.</div><div><br></div><div>Presently two options, enable_v1_api, and enable_v2_api prefix the help with DEPRECATED.</div><div>With my proposed change there are now the following additional options prefixed DEPRECATED. I've verified the code to be sure.</div><div><br></div><div>In the API table, secure_proxy_ssl_header (from oslo.middleware) [3]</div><div>In the flashsystem table, flashsystem_multipath_enabled [4]</div><div>In the logging table, verbose (from oslo.log) [5]</div><div>In the storwize table, storwize_svc_multihostmap_enabled [6]</div><div>In the zoning_fabric table, principal_switch_wwn [7]</div><div><br></div><div><br></div><div>[1] <a href="https://review.openstack.org/#/c/293697/">https://review.openstack.org/#/c/293697/</a></div><div>[2] <a href="https://review.openstack.org/#/c/293739/">https://review.openstack.org/#/c/293739/</a></div><div>[3]  <a href="http://git.openstack.org/cgit/openstack/oslo.middleware/tree/oslo_middleware/ssl.py#n20">http://git.openstack.org/cgit/openstack/oslo.middleware/tree/oslo_middleware/ssl.py#n20</a></div><div>[4]  <a href="http://git.openstack.org/cgit/openstack/cinder/tree/cinder/volume/drivers/ibm/flashsystem_fc.py#n49">http://git.openstack.org/cgit/openstack/cinder/tree/cinder/volume/drivers/ibm/flashsystem_fc.py#n49</a></div><div>[5] <a href="http://git.openstack.org/cgit/openstack/oslo.log/tree/oslo_log/_options.py#n44">http://git.openstack.org/cgit/openstack/oslo.log/tree/oslo_log/_options.py#n44</a></div><div>[6] <a href="http://git.openstack.org/cgit/openstack/cinder/tree/cinder/volume/drivers/ibm/storwize_svc/storwize_svc_common.py#n95">http://git.openstack.org/cgit/openstack/cinder/tree/cinder/volume/drivers/ibm/storwize_svc/storwize_svc_common.py#n95</a></div><div>[7] <a href="http://git.openstack.org/cgit/openstack/cinder/tree/cinder/zonemanager/drivers/brocade/brcd_fabric_opts.py#n56">http://git.openstack.org/cgit/openstack/cinder/tree/cinder/zonemanager/drivers/brocade/brcd_fabric_opts.py#n56</a></div><div><br></div><div>Regards</div><div><br></div><div>Ronald</div><div><br></div></div></div></div></div></div>
</div>