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? > Personally I find it highly useful to have complete examples of how to do > things with python-novaclient or python-openstackclient. I agree. Personally, I'd like to see something like Stripe's API docs [1], maybe through a not-yet-existant 'sphinx-slate' extension [2], but that seems a lot of work for very little gain and would need serious maintaining. > Given that any users of the raw HTTP API are likely going to be developers, > while users of the CLI tools may not be, it seems more important to give > good examples of using the CLI tools. Any developer should be able to figure > out the underlying HTTP (using the --debug option of the CLI tool if > necessary). I think the main idea is that the 'python-*client's are not the only game in town and should not be treated as such. Who these other clients are is a question I don't personally know the answer to, however. In any case, this is surely a post-Pike issue, as noted above. Stephen [1] https://stripe.com/docs/api [2] https://github.com/lord/slate __________________________________________________________________________ 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