Open Stack

cc'ed dtroyer (osc ptl)

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
http://docs.openstack.org/cli-reference/openstack.html and
http://docs.openstack.org/developer/python-openstackclient/command-list.html

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:
http://docs.openstack.org/developer/python-openstackclient/command-objects/volume-type.html#volume-type-create
but it is not reflected here:
http://docs.openstack.org/cli-reference/openstack.html#openstack-volume-type-create

If we can resolve this issue, then I think we can remove the docs from OSCs
page.



On Thu, Sep 1, 2016 at 5:08 PM, Lana Brindley <openstack at lanabrindley.com>
wrote:

> 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
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160901/59298c71/attachment-0001.html>