[docs] Documenting CLI references (openstack-auto-commands)

Sean McGinnis sean.mcginnis at gmx.com
Thu Apr 18 21:55:50 UTC 2019

Hey everyone,

Hoping someone has discussed this and has a recommended course of action.

Back when we had the awesome support of the openstack-docs team, there was a
command called openstack-auto-commands that would load up client commands and
generate help output for all commands. With the resource constraints that hit
the team, there were less folks to support tools like this. Docs moved into
each team's repos and, for the most part, I think that has worked out well.

Some of the automatic syncing stopped happening with this move to in-repo docs.
One of them was CLI docs. But it would appear there are at least a few teams
that now have not updated these docs since that move happened several releases


There are others that appear to have used the last automatically generated
version and have been (varying degrees of) successful at just manually updating
the doc as things change.

When the tool was removed (https://review.openstack.org/#/c/509402/) it was
stated that it wasn't needed because cliff has sphinx integration to do the
equivalent automatically. That's all well and good... if you are using cliff.
But I think many of our legacy clients are not.

So looking for recommendations on ways to best keep these docs up to date now.
Migrate to cliff? Other in-repo automation tools?

(and yeah, I know, "drop the CLI and move to openstackclient)

Thanks for any suggestions!


More information about the openstack-discuss mailing list