[OpenStack-docs] how is cli-ref generated?

Akihiro Motoki amotoki at gmail.com
Thu Sep 1 17:19:57 UTC 2016

Thanks for your replies and sharing the reference.

I see several points to be improved and the motivation of the original
mail came from them.
In addition to the original mail, let me share more points I see.
I would like to know what have been discussed in the docs team so far
and what are planned.

I am not sure I have enough time to initiate the effort, but I can
help the effort
as neutronclient lieutenant of the neutron team and an openstackclient


I wonder what is the criteria of inclusion of the openstack client cli-ref
http://docs.openstack.org/cli-reference/openstack.html .
Some commands come from openstackclient release itself, some come from
OSC plugin from various repositories,
and some OSC plugin commands are not covered.
(For example, baremetal OSC plugin commands are covered but neutron
OSC plugin command are not covered.)
OSC now uses OSC plugin mechanism and recommends the adoption of OSC plugin way.
It seems the current way of OSC CLI reference generation needs to be revisited.

OSC also recently introduced "beta" command concept [1].
Another point is how the cli-ref provided by openstack-manuals treats it.
[1] http://docs.openstack.org/developer/python-openstackclient/command-beta.html

As a user of OpenStack cloud, I am not sure which is better cli-ref of
OSC from openstackclient or openstack-manuals.
Anyway I think the cli-ref portion of the docs team needs more
collaboration with the client team.
OSC is becoming our single CLI gradually.


2016-09-01 7:32 GMT+09:00 Lana Brindley <openstack at lanabrindley.com>:
> There's also info here: http://docs.openstack.org/contributor-guide/doc-tools/cli-reference.html
> L
> On 01/09/16 03:48, Steve Martinelli wrote:
>> for reference, the help that the docs team publishes is here: http://docs.openstack.org/cli-reference/openstack.html
>> and the one that the OSC team publishes is here: http://docs.openstack.org/developer/python-openstackclient/command-list.html
>> I was under the impression that the first one (published by the docs team) was done with automation
>> On Wed, Aug 31, 2016 at 1:36 PM, Akihiro Motoki <amotoki at gmail.com <mailto:amotoki at gmail.com>> wrote:
>>     Hi,
>>     I wonder how CLI reference is generated?
>>     I looked for some document on the process of the CLI reference but I
>>     failed to find it.
>>     This question mainly comes from the following two.
>>     (1) Why the process is not automated?
>>     I see a lot of patches to CLI reference when new version of CLIs are release.
>>     I wonder why they are not automated.
>>     (2) Duplicated information on OSC
>>     OSC provides useful and detail command line help in their devref.
>>     OSC CLI reference in openstack-manuals looks like a duplicated effort.
>>     If the docs team has not talked with OSC team, it means a lack of
>>     communications.
>>     Anyway, I think we should try and explore more automated way
>>     rather than spend time to keep them up-to-date manually.
>>     Thought?
>>     Thanks,
>>     Akihiro
>>     _______________________________________________
>>     OpenStack-docs mailing list
>>     OpenStack-docs at lists.openstack.org <mailto:OpenStack-docs at lists.openstack.org>
>>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> --
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> http://lanabrindley.com
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

More information about the OpenStack-docs mailing list