codehaus


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[cinder][osc][docs] openstackclient docs for cinder v2 vs v3


Howdy cinderinos.

I've been on a mission to get all of the python-openstackclient command
[1] and plugin [2] docs autogenerated rather than hardcoded [3] so you
don't have to remember to update two places when you add/change a
subcommand option. I'm almost done -- cinder is the last one -- but I
want to confirm some odd observations before I dig in.

- All of the v3 subcommands are implemented by code in the
openstackclient.volume.v2 package. Where there's overlap, the command
classes are identical from v2 to v3. However, it appears as though the
v2 commands are a *superset* of the v3 commands. Specifically, the
following appear in v2 but not v3 [4]:

     volume_backup_record_export
     volume_backup_record_import

     volume_backend_capability_show
     volume_backend_pool_list

     volume_host_failover

Observations:
  * v3 has no other 'volume backup record' subcommands, but otherwise
has the same 'volume backup' subcommands as v2.
  * v3 has no 'volume backend' subcommands.
  * v2 has both 'volume host failover' and 'volume host set', but v3 has
only the latter.
  * It seems suspicious that the "missing" v3 commands comprise a
contiguous block under the v2 entry point.

So before I go creating a mess of v2-only and v2+v3 documents, I wanted
to confirm that the above was actually intentional.

- The existing hardcoded documents mention v1 and/or v2, but don't
mention v3 at all (e.g. [5]). I want to confirm that it's okay for me to
add mention of v3 where appropriate.

Thanks,
efried

[1]
https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html
[2]
https://docs.openstack.org/python-openstackclient/latest/cli/plugin-commands/index.html
[3]
https://review.opendev.org/#/q/topic:generate-docs+(status:open+OR+status:merged)
[4]
https://opendev.org/openstack/python-openstackclient/src/tag/4.0.0/setup.cfg#L610-L616
[5]
https://docs.openstack.org/python-openstackclient/train/cli/command-objects/volume.html