Open Stack

Anne,
   Thanks, just what I needed. In the Compute API, the Type column does not appear to have a ‘uuid’
value. I see ‘string’ in cases where the type is obviously uuid. Is that an oversight?

-        Louis

From: Anne Gentle [mailto:annegentle at justwriteclick.com]
Sent: Thursday, May 19, 2016 9:24 AM
To: Henry Fourie
Cc: openstack-docs at lists.openstack.org
Subject: Re: [OpenStack-docs] Style column in OpenStack API docs

The most-complete project is nova, look here:
http://developer.openstack.org/api-guide/compute/
http://developer.openstack.org/api-ref/compute/

We definitely need more work on tying the information together across projects and for api-ref and api-guide. Looking for web dev/design help for that.

Anne

On Thu, May 19, 2016 at 11:20 AM, Henry Fourie <louis.fourie at huawei.com<mailto:louis.fourie at huawei.com>> wrote:
Anne,
   Done that. What I meant was API documentation for other projects I could look at.

-        Louis

From: Anne Gentle [mailto:annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>]
Sent: Wednesday, May 18, 2016 7:13 PM

To: Henry Fourie
Cc: openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>
Subject: Re: [OpenStack-docs] Style column in OpenStack API docs

You can build locally with tox -e api-ref. Copy the tox.ini config from the examples. Once you have a gate job you can see it with every patch.

Thanks,
Anne


On May 18, 2016, at 5:57 PM, Henry Fourie <louis.fourie at huawei.com<mailto:louis.fourie at huawei.com>> wrote:
Anne,
   Thanks. Is there an example of new API documentation I could inspect
to see if the API docs I create are on the right track?

-        Louis

From: Anne Gentle [mailto:annegentle at justwriteclick.com]
Sent: Wednesday, May 18, 2016 3:17 PM
To: Henry Fourie
Cc: openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>
Subject: Re: [OpenStack-docs] Style column in OpenStack API docs



On Wed, May 18, 2016 at 3:25 PM, Henry Fourie <louis.fourie at huawei.com<mailto:louis.fourie at huawei.com>> wrote:
Anne,
  So for new APIs the procedure for API documentation is as described here?
http://docs.openstack.org/contributor-guide/api-guides.html


Yes.

When will the neutron API be converted to use parameters.yaml?


Yes, the review.openstack.org<http://review.openstack.org> link at https://review.openstack.org/#/c/314819<https://review.openstack.org/#/c/314819/> is to the patch where the conversion is being reviewed now.

I am adding API documentation for networking-sfc. Once I have added the necessary files

to api-ref/source, and verified them with tox -e api-ref what must I do to get the

resulting documentation published to say http://docs.openstack.org/mitaka/networking-sfc

You have the idea. There's a need for a second patch like this one for swift, https://review.openstack.org/#/c/313015/ that creates the infrastructure jobs to publish to developer.openstack.org/api-ref/<http://developer.openstack.org/api-ref/><servicename>/ such as http://developer.openstack.org/api-ref/compute/. If you have a networking-sfc repo, then you'll need two patches to get your API ref publishing, one for the source code repo, one for the project-config repo.

Hope that helps -
Anne



-        Louis

From: Anne Gentle [mailto:annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>]
Sent: Wednesday, May 18, 2016 1:14 PM

To: Henry Fourie
Cc: openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>
Subject: Re: [OpenStack-docs] Style column in OpenStack API docs

Thanks for the link.

That's from WADL, the style attribute. See this line in the source:
https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/networking-api/src/wadl/networks.wadl#L93

For the new parameters.yaml file, there aren't style attributes. Rather, there's these attributes per param, in, required, and type:
param-name:
  in: body
  required: true
  type: boolean

See
https://review.openstack.org/#/c/314819/1/api-ref/source/v2/parameters.yaml for the new format.

Hope this info helps - let me know what you're looking to do with the info.
Anne

On Wed, May 18, 2016 at 3:05 PM, Henry Fourie <louis.fourie at huawei.com<mailto:louis.fourie at huawei.com>> wrote:
Anne,
  See for example http://developer.openstack.org/api-ref-networking-v2.html
Click on Detail for Networks to see Request or Response parameter tables.

-        Louis


From: Anne Gentle [mailto:annegentle at justwriteclick.com<mailto:annegentle at justwriteclick.com>]
Sent: Wednesday, May 18, 2016 1:01 PM
To: Henry Fourie
Cc: openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>
Subject: Re: [OpenStack-docs] Style column in OpenStack API docs

Hi Louis,
Can you send a link or screenshot of what you mean by the Style column? I'm not sure what you're looking at and the API docs are transitioning to RST + YAML, built with Sphinx. So, let me know more about where you see this column and what you'd like to do once you learn more.
Thanks,
Anne

On Wed, May 18, 2016 at 2:35 PM, Henry Fourie <louis.fourie at huawei.com<mailto:louis.fourie at huawei.com>> wrote:
What is the usage of the Style column in OpenStack API docs?
How is this column created?

-        Louis


_______________________________________________
OpenStack-docs mailing list
OpenStack-docs at lists.openstack.org<mailto:OpenStack-docs at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs



--
Anne Gentle
www.justwriteclick.com<http://www.justwriteclick.com>



--
Anne Gentle
www.justwriteclick.com<http://www.justwriteclick.com>



--
Anne Gentle
www.justwriteclick.com<http://www.justwriteclick.com>



--
Anne Gentle
www.justwriteclick.com<http://www.justwriteclick.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160519/0a6a4c8a/attachment-0001.html>