Open Stack

Excerpts from Sean Dague's message of 2017-08-02 14:34:40 -0400:
> On 08/02/2017 12:20 PM, Doug Hellmann wrote:
> > 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.
> 
> It's not so simple because years ago we decided nova-manage was mostly a
> bad thing (as you needed to run it on the API node and be able to read
> db creds with it), and exposed as much as possible of the administrative
> interfaces over the API. The policy of openstack client was that
> administrative commands would not go in openstack client. So a bunch of
> what was once nova-manage (5 years ago), is part of the nova cli now,
> and not really implemented by other toolkits.
> 
> This is also why the python nova client is not going away any time soon.
> 
>     -Sean
> 

That's fine. I still think that if the instructions are "how to use
the nova client to do X" then they should go in the nova client
repository, because they are really about how to use *that tool*
to do the task.  If they are written from the perspective of "how
to do X with the nova API", that's a different case and it makes
sense to put them in the nova repository.

Ultimately, though, it's up to the nova team to decide where they want
to put the docs.

Doug