Open Stack

Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:
> 2017-08-03 0:52 GMT+09:00 Doug Hellmann <doug at doughellmann.com>:
> > Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
> >> On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
> >> > On 08/02/2017 09:22 AM, Stephen Finucane wrote:
> >> > > On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> >> > > > 3. The patch for the import of the admin guide [8] is missing some CLI
> >> > > > specific pages which are pretty useful given they aren't documented
> >> > > > anywhere else, like the forced_host part of the compute API [9].
> >> > > > Basically anything that's cli-nova-* in the admin guide should be in the
> >> > > > Nova docs. It's also missing the compute-flavors page [10] which is
> >> > > > pretty important for using OpenStack at all.
> >> > >
> >> > > This is a tricky one. Based on previous discussions with dhellmann, the
> >> > > plan
> >> > > seems to be to replace any references to 'nova xxx' or 'openstack xxx'
> >> > > commands
> >> > > (i.e. commands using python-novaclient or python-openstackclient) in favour
> >> > > of
> >> > > 'curl'-based requests. The idea here is that the Python clients are not the
> >> > > only clients available, and we shouldn't be "mandating" their use by
> >> > > referencing them in the docs. I get this, though I don't fully agree with
> >> > > it
> >> > > (who really uses curl?)
> >> >
> >> > Are we going to document the python clients elsewhere then?
> >>
> >> I think the docs would go into the respective python clients docs?
> >
> > Right. I don't remember the details of the curl discussion, but I
> > think what I was trying to say there was that the "nova" command
> > line tool installed via python-novaclient should be documented as
> > part of the openstack/python-novaclient repo rather than openstack/nova.
> > A CLI reference for nova-manage, which I think is in openstack/nova,
> > could be documented in openstack/nova.
> >
> > Basically, put the docs with the code, which is the whole point of this
> > migration.
> 
> It is true for CLI reference.
> The gray zone is CLI stuffs in the admin guide and/or end-user guide.
> I think this is the point Matt raised.
> cli-nova-* stuffs in the admin guide was per topic like launching instance,
> migrating instances and so on. It is actually beyond the CLI reference to me.
> It is about how to use specific features of nova.
> IMHO this kind of stuffs can be covered by the admin guide or user guide,
> so it fits into openstack/nova (or other server projects).

Yeah, I don't know.

My gut response is to say that if the example uses nova-manage or
one of the nova service executables, then that makes sense to leave
in the nova tree, but otherwise it should go into either the
python-novaclient or python-openstackclient repositories (depending
on which command line tool is used in the example).

On the other hand, I can see that being somewhat confusing for
someone who lands at the nova docs and can't find instructions for
how to use it. Maybe less confusing, though, than if I am not
*running* nova but am trying to use a nova deployed by someone else
and I start from the python-novaclient or python-openstackclient
docs because I installed one of those in order to talk to nova.

I thought "put the docs with the code" would be a simple enough
rule that we wouldn't have to think too hard about where to put
individual example files, which would speed up the migration.

Doug

> 
> Akihiro
> 
> >
> > Doug
> >
> > __________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>