[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.ht... [2] https://docs.openstack.org/python-openstackclient/latest/cli/plugin-commands... [3] https://review.opendev.org/#/q/topic:generate-docs+(status:open+OR+status:me...) [4] https://opendev.org/openstack/python-openstackclient/src/tag/4.0.0/setup.cfg... [5] https://docs.openstack.org/python-openstackclient/train/cli/command-objects/...
On Tue, Nov 5, 2019 at 10:26 AM Eric Fried <openstack@fried.cc> wrote:
- 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]:
A number of commands were deprecated between v2 and v3, some were just renamed. However, that crux of this problem is that this pass-through was ever done in the first place. This is the only place in OSc that we did this rather than just copy the code between the API version modules. IMO that is what we need to finally do to fix this, complete the actual duplication of the v2 bits still being called by v3 in the v3 directories.
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.
Again, folks wanted to avoid doing the work to set up v3 properly, now the debt collector comes calling...I would hold off doing anything with the docs until the code and tests have been properly straightened out. dt -- Dean Troyer dtroyer@gmail.com
participants (2)
-
Dean Troyer
-
Eric Fried