[openstack-dev] [nova][docs] Concerns with docs migration
sfinucan at redhat.com
Wed Aug 2 15:35:23 UTC 2017
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  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 .
> > > Basically anything that's cli-nova-* in the admin guide should be in the
> > > Nova docs. It's also missing the compute-flavors page  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 ,
maybe through a not-yet-existant 'sphinx-slate' extension , 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
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.
More information about the OpenStack-dev