Open Stack

Hi Steve,

Note that the two api-ref.xml docs in the two repos have different purposes:

  *   Heat repo: the api-ref.xml doc in this repo is the source for the Orchestration API Dev Guide (which I am planning to start working on), and provides detailed information and examples for each API call. You can see examples of these Dev Guides at docs.openstack.org, such as the OpenStack Compute API v2 and Extensions Reference at http://docs.openstack.org/api/openstack-compute/2/content/. I will be working on producing this doc for the Orchestration project.
  *   Orchestration repo (api-site):  the api-ref.xml doc in this repo is the source for the API Complete Reference, which provides a summary of all the calls for all the OpenStack products (http://api.openstack.org/api-ref.html).

We need to support both of these moving forward, so I would prefer if you don't delete the files listed in your review (https://review.openstack.org/#/c/46412/) — except please do delete the heat-api-1.0.wadl, which is no longer needed, since we now have the orchestration-api.wadl in the api-site repo. We need the other files to remain, since they provide the infrastructure for the Orchestration Dev Guide (pom.xml, api-ref.xml, and example files) that we need to produce.

Mike
From: Steve Baker <sbaker at redhat.com<mailto:sbaker at redhat.com>>
Reply-To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Wednesday, September 18, 2013 2:08 PM
To: "openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>" <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Subject: Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward

On 09/18/2013 08:09 AM, Mike Asthalter wrote:
We were successful yesterday in accessing the orchestration-api wadl in the api-site repo from the api-ref dev guide (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml) in the original heat repo using the following syntax in the api-ref.xml doc:


<wadl:resources
            href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl"<http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl>
            xmlns:wadl="http://wadl.dev.java.net/2009/02"<http://wadl.dev.java.net/2009/02>/>

Therefore, as recommended in our discussion on this mailing list last week, I am planning to submit a patch to delete the original heat wadl (heat-api-1.0.wadl) and to point the api-ref.xml doc at the orchestration-api.wadl in the api-site repo, as shown above.

Please let me know by tomorrow if anyone has any objections to deleting the original heat wadl, heat-api-1.0.wadl.

There is already a change in progress to delete all of heat's api-ref
https://review.openstack.org/#/c/46412/

On a related note, Anne Gentle has recommended the following:

"What we also need to build is logic in the build jobs so that any time the api-site WADL is updated, your dev guide is also updated. This is done in the Jenkins job in https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/api-jobs.yaml. I can either submit this patch for you, or I'll ask Steve or Zane to do so."

Steve or Zane, is submitting this patch for the build logic something you would like to do, or should we ask Anne to take care of it?


I would think that there is no need at all now for heat/doc/docbkx/api-ref since it is part of api.site. Does this mean there is no need for an update job?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130918/ddea428c/attachment.html>