[openstack-dev] [Doc] Inclusion of microversion API support in CLI reference

Andreas Jaeger aj at suse.com
Wed Oct 12 15:49:27 UTC 2016


On 10/12/2016 03:03 PM, Sean McGinnis wrote:
> Just getting this out there to either get educated or to start a
> conversation...
> 
> While going through some of the DocImpact generated bugs for
> python-cinderclient I noticed a few that added new parameters to
> existing CLI commands. As Cinder has now moved to using microversions
> for all API changes, these new parameters are only available at a
> certain microversion level.
> 
> A specific case is here:
> 
> https://github.com/openstack/python-cinderclient/blob/master/cinderclient/v3/shell.py#L1485
> 
> We have two parameters that are marked "start_version='3.1'" that do not
> show up in the generated CLI reference.
> 
> This appears to be due to (or related to) the fact that the command line
> help does not output anything for these. Now before I dig into why that
> is, I know there are others that are already much more knowledgable
> about this area than I am. So my question is, is this by design? Or is
> something missing here that is needed to recognize these params with the
> start_version value so they get printed?
> 
> My expectation as an end user would be that the help information would
> be printed, with something like "(Requires API 3.1 or later)" appended
> to the help text.
> 
> Anyone have any insight on this?

These are always challenges ;) We generate the help using the
doc-tools-update-cli-reference command from openstack-doc-tools and I
don't think we have special code in os_doc_tools/commands.py to handle
this yet.

For some commands, we run the help twice with different parameters - and
we could add for cinder the start_version for sure. I just hope it does
not remove older commands at the same time ;)


Adding docs mailing list,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126




More information about the OpenStack-dev mailing list