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

Lana Brindley openstack at lanabrindley.com
Thu Sep 1 21:08:51 UTC 2016


The CLI reference falls under the purview of the Config Reference team, which is headed up by KATO Tomoyuki. I've cc'd Tomoyuki-san in this email, and he can help you to understand what is required.

Lana

On 02/09/16 03:19, Akihiro Motoki wrote:
> 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
> contributor.
> 
> ---
> 
> 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.
> 
> Thanks,
> Akihiro
> 
> 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
>>
> 
> _______________________________________________
> 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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160902/ca196d56/attachment.pgp>


More information about the OpenStack-docs mailing list