<div dir="ltr">cc'ed dtroyer (osc ptl)<div><br></div><div>Duplication is a part of Akihiro's initial comment, and I think the the OSC shouldn't maintain it's own copy of this, but rather redirect to the docs page. I'd be more than happy to get rid of the OSC docs, before doing that I did a quick comparison between <a href="http://docs.openstack.org/cli-reference/openstack.html">http://docs.openstack.org/cli-reference/openstack.html</a> and <a href="http://docs.openstack.org/developer/python-openstackclient/command-list.html">http://docs.openstack.org/developer/python-openstackclient/command-list.html</a><div><br></div><div>The only information that I see missing is that in the OSC docs we mark some options (and commands) as being specific to an API version. For instance, in "volume type create", the description, public, private, and project options are only supported for the Volume V2 API (we (OSC) can't do anything about this limitation). We document this limitation as such here: <a href="http://docs.openstack.org/developer/python-openstackclient/command-objects/volume-type.html#volume-type-create">http://docs.openstack.org/developer/python-openstackclient/command-objects/volume-type.html#volume-type-create</a> but it is not reflected here: <a href="http://docs.openstack.org/cli-reference/openstack.html#openstack-volume-type-create">http://docs.openstack.org/cli-reference/openstack.html#openstack-volume-type-create</a></div><div><br></div><div>If we can resolve this issue, then I think we can remove the docs from OSCs page.</div><div><br></div><div><br></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Sep 1, 2016 at 5:08 PM, Lana Brindley <span dir="ltr"><<a href="mailto:openstack@lanabrindley.com" target="_blank">openstack@lanabrindley.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">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.<br>
<span class="HOEnZb"><font color="#888888"><br>
Lana<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
On 02/09/16 03:19, Akihiro Motoki wrote:<br>
> Thanks for your replies and sharing the reference.<br>
><br>
> I see several points to be improved and the motivation of the original<br>
> mail came from them.<br>
> In addition to the original mail, let me share more points I see.<br>
> I would like to know what have been discussed in the docs team so far<br>
> and what are planned.<br>
><br>
> I am not sure I have enough time to initiate the effort, but I can<br>
> help the effort<br>
> as neutronclient lieutenant of the neutron team and an openstackclient<br>
> contributor.<br>
><br>
> ---<br>
><br>
> I wonder what is the criteria of inclusion of the openstack client cli-ref<br>
> <a href="http://docs.openstack.org/cli-reference/openstack.html" rel="noreferrer" target="_blank">http://docs.openstack.org/cli-<wbr>reference/openstack.html</a> .<br>
> Some commands come from openstackclient release itself, some come from<br>
> OSC plugin from various repositories,<br>
> and some OSC plugin commands are not covered.<br>
> (For example, baremetal OSC plugin commands are covered but neutron<br>
> OSC plugin command are not covered.)<br>
> OSC now uses OSC plugin mechanism and recommends the adoption of OSC plugin way.<br>
> It seems the current way of OSC CLI reference generation needs to be revisited.<br>
><br>
> OSC also recently introduced "beta" command concept [1].<br>
> Another point is how the cli-ref provided by openstack-manuals treats it.<br>
> [1] <a href="http://docs.openstack.org/developer/python-openstackclient/command-beta.html" rel="noreferrer" target="_blank">http://docs.openstack.org/<wbr>developer/python-<wbr>openstackclient/command-beta.<wbr>html</a><br>
><br>
> As a user of OpenStack cloud, I am not sure which is better cli-ref of<br>
> OSC from openstackclient or openstack-manuals.<br>
> Anyway I think the cli-ref portion of the docs team needs more<br>
> collaboration with the client team.<br>
> OSC is becoming our single CLI gradually.<br>
><br>
> Thanks,<br>
> Akihiro<br>
><br>
> 2016-09-01 7:32 GMT+09:00 Lana Brindley <<a href="mailto:openstack@lanabrindley.com">openstack@lanabrindley.com</a>>:<br>
>> There's also info here: <a href="http://docs.openstack.org/contributor-guide/doc-tools/cli-reference.html" rel="noreferrer" target="_blank">http://docs.openstack.org/<wbr>contributor-guide/doc-tools/<wbr>cli-reference.html</a><br>
>><br>
>> L<br>
>><br>
>> On 01/09/16 03:48, Steve Martinelli wrote:<br>
>>> for reference, the help that the docs team publishes is here: <a href="http://docs.openstack.org/cli-reference/openstack.html" rel="noreferrer" target="_blank">http://docs.openstack.org/cli-<wbr>reference/openstack.html</a><br>
>>><br>
>>> and the one that the OSC team publishes is here: <a href="http://docs.openstack.org/developer/python-openstackclient/command-list.html" rel="noreferrer" target="_blank">http://docs.openstack.org/<wbr>developer/python-<wbr>openstackclient/command-list.<wbr>html</a><br>
>>><br>
>>> I was under the impression that the first one (published by the docs team) was done with automation<br>
>>><br>
>>> On Wed, Aug 31, 2016 at 1:36 PM, Akihiro Motoki <<a href="mailto:amotoki@gmail.com">amotoki@gmail.com</a> <mailto:<a href="mailto:amotoki@gmail.com">amotoki@gmail.com</a>>> wrote:<br>
>>><br>
>>> Hi,<br>
>>><br>
>>> I wonder how CLI reference is generated?<br>
>>> I looked for some document on the process of the CLI reference but I<br>
>>> failed to find it.<br>
>>><br>
>>> This question mainly comes from the following two.<br>
>>><br>
>>> (1) Why the process is not automated?<br>
>>> I see a lot of patches to CLI reference when new version of CLIs are release.<br>
>>> I wonder why they are not automated.<br>
>>><br>
>>> (2) Duplicated information on OSC<br>
>>> OSC provides useful and detail command line help in their devref.<br>
>>> OSC CLI reference in openstack-manuals looks like a duplicated effort.<br>
>>> If the docs team has not talked with OSC team, it means a lack of<br>
>>> communications.<br>
>>><br>
>>> Anyway, I think we should try and explore more automated way<br>
>>> rather than spend time to keep them up-to-date manually.<br>
>>><br>
>>> Thought?<br>
>>><br>
>>> Thanks,<br>
>>> Akihiro<br>
>>><br>
>>> ______________________________<wbr>_________________<br>
>>> OpenStack-docs mailing list<br>
>>> <a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a> <mailto:<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a>><br>
>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a> <<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a>><br>
>>><br>
>>><br>
>>><br>
>>><br>
>>> ______________________________<wbr>_________________<br>
>>> OpenStack-docs mailing list<br>
>>> <a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a><br>
>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a><br>
>>><br>
>><br>
>> --<br>
>> Lana Brindley<br>
>> Technical Writer<br>
>> Rackspace Cloud Builders Australia<br>
>> <a href="http://lanabrindley.com" rel="noreferrer" target="_blank">http://lanabrindley.com</a><br>
>><br>
>><br>
>> ______________________________<wbr>_________________<br>
>> OpenStack-docs mailing list<br>
>> <a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a><br>
>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a><br>
>><br>
><br>
> ______________________________<wbr>_________________<br>
> OpenStack-docs mailing list<br>
> <a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a><br>
><br>
<br>
--<br>
Lana Brindley<br>
Technical Writer<br>
Rackspace Cloud Builders Australia<br>
<a href="http://lanabrindley.com" rel="noreferrer" target="_blank">http://lanabrindley.com</a><br>
<br>
</div></div><br>______________________________<wbr>_________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a><br>
<br></blockquote></div><br></div>