Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900: > 2017-08-03 0:52 GMT+09:00 Doug Hellmann <d...@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-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev