Open Stack

On Mon, Jul 28, 2014 at 4:24 PM, Jorge Williams <
jorge.williams at rackspace.com> wrote:

> Maybe we need to rethink our model.  Rather than reaching directly to a
> HTTP URI in github, we can instead list the WADL as a dependency in maven.
>  Should be possible, we can tar up the api-ref project, have a deployment
> that stores it somewhere — maybe maven central…then when we build our docs
> we download and extract the correct version and tie everything together.
>
>
I've talked about that before with David Cramer when working through a
content sharing blueprint. We have a blueprint [1] [2] we worked on. I
recently marked it Obsolete for a few reasons:
- We have a reliable HTTP URI from git.openstack.org (we don't rely on
github)
- We haven't had a lot of multiple-collaboration scenarios on API docs
(Diane has been our go-to for a long time [3])
- We aren't seeing much upstream contribution work from cloud providers on
API docs

So I'd prefer we don't try to engineer this solution. Really I'd prefer
that we stop building and publishing documents from the <servicename>-api
repos for a couple of reasons:
- We had agreement two summits ago to stop storing those sources in
separate repos
- There's a serious bug with the <servicename>-api output where it doesn't
show all the parameters for each call. [4]

With all the difficulty we're seeing, I think this is a symptom of a wider
problem and we should try to find a simpler way to maintain API docs. Any
other thoughts?

Anne

1. https://wiki.openstack.org/wiki/Documentation/ContentSharing
2.
https://blueprints.launchpad.net/openstack-manuals/+spec/design-content-sharing
3.
http://stackalytics.com/?release=icehouse&project_type=documentation&module=api-site&metric=commits
4. https://bugs.launchpad.net/openstack-manuals/+bug/1342379 and
https://bugs.launchpad.net/openstack-api-site/+bug/1300249




> -jOrGe W.
>
>
>
>
> On Jul 28, 2014, at 3:01 PM, Andreas Jaeger <aj at suse.com> wrote:
>
> > On 07/28/2014 09:49 PM, Christian Berendt wrote:
> >> On 07/28/2014 09:46 PM, Anne Gentle wrote:
> >>> We already do test and gate on something building, but the problem was
> >>> with two repos, so I think is that he "race condition" problem we see
> in
> >>> other cross-repo dependencies?
> >>
> >> I mean the cross-repo dependencies. Is it not possible to build checks
> >> to check if identity-api still builds when changing something in
> api-site?
> >
> > Since we're not providing a "binary" that can be used in the environment
> > but instead download directly from the other git repository, I do not
> > see how to implement this.
> >
> > Also, how are we getting in a change that renames a file in one
> > repository and the change for that in the other one together?
> >
> > So, as much as I would like to see such gating done for these few repos,
> > I have no clever idea. If you have one, please write up a blueprint,
> >
> > 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
> >
> > _______________________________________________
> > Openstack-docs mailing list
> > Openstack-docs at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140728/a15e4d88/attachment.html>