Open Stack

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