[openstack-dev] [nova][docs] Concerns with docs migration

Chris Friesen chris.friesen at windriver.com
Wed Aug 2 15:28:18 UTC 2017


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?  Personally I find 
it highly useful to have complete examples of how to do things with 
python-novaclient or python-openstackclient.

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).

Chris



More information about the OpenStack-dev mailing list