Restore OpenStack command list in Command-Line Interface Reference

[Michael Foster]

The Command-line reference page used to (appropriately) list all of the available commands for the python-openstack client. However, now the page points to a developer document here: http://docs.openstack.org/developer/python-openstackclient/

from which you have to click here: http://docs.openstack.org/developer/python-openstackclient/command-list.html

This page lists the commands as yet more links, but to individual commands instead of the full list. The page is also missing some core modules like all of the Orchestration (HEAT) commands.

Please restore the single page listing of the python-openstack client similar to what is listed here for glance:

http://docs.openstack.org/cli-reference/glance.html

-----------------------------------
Release: 0.9 on 2016-09-26 11:07
SHA: 7b52290f9af69d8afbbaf0216adb4366f0768dbf
Source: http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/cli-reference/source/openstack.rst
URL: http://docs.openstack.org/cli-reference/openstack.html

[Lana (loquacity)]

Hi Michael, I see the point here, but the openstackclient is actually a separate project, who look after the documentation. Also, that list is incredibly long and subject to change, so pointing to the client documentation means we're not maintaining it in two places. I've added Tomoyuki Kato to this bug, though, for his comment.

[KATO Tomoyuki (kato-tomoyuki)]

As Lana said, the reference for the "openstack" command is maintained at the python-openstackclient project. I generally like your idea, but we need discussion with them.

[Steve Martinelli (stevemar)]

I think we brought this up on the mailing list at one point. It's made more difficult since openstackclient has many plugins (heat being one of them), which is why you won't see heat commands here: http://docs.openstack.org/developer/python-openstackclient/command-list.html

I do not mind the docs team publishing their own version of it, IIRC there was tooling around this? It would be nice to have everything in one spot (for all the plugins).

I know one of the reasons why we keep our own version is because sometimes we add a bit more information to a specific command or command class, along with the help and options.

[Michael Foster (mfosterm)]

Thanks for the feedback. I found the Change-ID that removed all of the content (Change-Id: I0e530e93ac1ce0f273562561465794d4dc460036) and the discussion you were referring to [1].

I can see the point of trying to reduce duplication. However, as an end-user, having all of the information in one place is crucial. As I mentioned, the developer page is woefully incomplete.
Additionally, since the trend is to be migration away from the individual clients to the centralized openstack client, there needs to be documentation for it, especially since some commands are not 1-for-1. Trying to find an openstack cli equivalent is made harder when you can't search on a specific term unless you know which command you need help with. I often find myself searching for a command-line switch to find what the actual command is. A trivial example would be trying to set a tag on a glance image. The glance cli uses "image-tag-update", but the openstack cli uses the image-set command.

As an aside, end-user guides or admin guides for any of the supported projects should not redirect to developer documentation which is often terse and/or incomplete. For example trying to comprehensive docs on how to install or even use some projects like trove or manila is like pulling teeth. The "official" guides should be self-contained and as comprehensive as possible.

Apologies if this was too much of a rant. Thanks for looking.

[1] http://lists.openstack.org/pipermail/openstack-docs/2016-September/009095.html