Open Stack

On Sat, Aug 2, 2014 at 1:20 PM, Andreas Jaeger <aj at suse.com> wrote:

> On 08/02/2014 05:25 AM, Anne Gentle wrote:
> >
> >
> > On Tue, Jul 29, 2014 at 11:51 AM, <dfleming at austin.rr.com
> > <mailto:dfleming at austin.rr.com>> wrote:
> >
> >     Also, if we move that content to the api-site/api-ref-guides
> >     directory, the guides would point directly to the WADLs in
> >     api-site/api-ref directory, so they pick up current content rather
> >     than pointing to what's merged into master by way of URL.
> >
> >
> > Hi all,
> > Diane had a great idea over breakfast about how to mitigate these
> > issues, and I've put together a pair of patches that put the solution in
> > place to see what others think.
> >
> > The idea is to stop embedding WADL references in the Dev References and
> > instead link to the HTML output. Any relevant info for a particular call
> > moves into the WADL itself.
> >
> > I think this solves many of the issues I listed previously, so please
> > review this approach and let us know what you think on the review (or
> > here on the mailing list thread).
>
> There's still a tight coupling between these - whenever an URL in the
> api-site changes, we might need to adjust compute-api. Is there no way
> to avoid this duplication completely?
>

I agree, it's better to avoid the duplication, but this can be an interim
step to get time to write the "all OpenStack API" guide that would
consolidate all of the <project>-api repos for end-users and move the
"specs" into <project> repos.

We have this as Goal #4 here:
https://wiki.openstack.org/w/index.php?title=Blueprint-os-api-docs#Goal_4_-_Move_API_Specs_to_project_repositories_and_off_docs_landing_page

The blueprint got marked implemented even though that step isn't complete.



>
> The one nice thing with WADLs is that if the link is wrong, you get a
> build time error - with this change, it's a silent failure.
>
> I do like the idea but the above concerns me. Thanks for looking into this!
>
> > These examples are for Compute API v2, I'd do the same for Identity API
> > docs and others with embedded WADL in the Dev Ref.
> >
> > https://review.openstack.org/111436
> >
> > https://review.openstack.org/#/c/111435/
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140803/823def2f/attachment.html>