Open Stack

On Sun, Apr 27, 2014 at 12:19 PM, Andreas Jaeger <aj at suse.com> wrote:

> The documentation team noticed that we have links in the version
> responses of several APIs that contain URLs that do not exist at all.
>
> For example, cinder includes a link to
> "
> http://jorgew.github.com/block-storage-api/content/os-block-storage-1.0.pdf
> "
> - and jorgew.github.com does not exist as host at all.
>
> The links we're concerned about are the links to WADL and PDF files.
>
> Even if we update the links to point to valid URLs, it takes away any
> flexibility for the documentation team to move files around on the
> server.
>
> Diane Fleming and myself therefore propose to remove all the WADL
> links completely and have the PDF links just point to
> http://docs.openstack.org. So, moving forward with Juno (unless this
> gets backported), the content would be valid.
>
> But what about existing installations that already include links? Some
> of the existing links work - or worked a few months ago before some
> files got moved around. We could try to fix docs.openstack.org so that
> the WADL and PDF links to docs.openstack.org (so, not the cinder example
> above) work somehow:
> 1) Add redirects to current versions of WADL and PDF
> 2) Add redirects to just http://docs.openstack.org/index.html
>
> Since this affects several projects and is somehow user visible, we
> brought it up for discussion here. Note that some of these links seems
> to be broken for a very long time. The proposed changes do not break
> programs using the API - just users that look at the result of it in
> existing installations.
>
> So, my proposal would be:
> * Remove WADL links
>

I think this is fine going forward (as we're focusing on the JSON
interfaces), but I'm curious to know if anyone thinks this would be a
backportable change. I'd like to consider it, but while these are
documentation links, a WADL link is potentially designed for machine
consumption, so this could potentially break someone. I don't know that we
maintain our WADLs well enough for them to be useful in the real world,
though.


> * Have PDF links to go http://docs.openstack.org


As mentioned in the code review below, this needs to be revised to
text/html if it's going to point directly to a website rather than a PDF. I
imagine this change should also be backportable for those APIs that have
been broken for "a very long time."


>
> * For those current links to the site http://docs.openstack.org: Take
>   care that they point either to a current file or get redirected to
>   http://docs.openstack.org/index.html
>
> What do you think?
>
> Andreas
>
> For more details see these bugs:
> cinder v2: https://bugs.launchpad.net/cinder/+bug/1313116
> cinder v1: https://bugs.launchpad.net/cinder/+bug/1313118
> nova v2 and v3: https://bugs.launchpad.net/nova/+bug/1313119
> identity v2.0 and v3: https://bugs.launchpad.net/keystone/+bug/1313127
>
> A patch for Cinder is at https://review.openstack.org/90554
>
> --
>  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-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140427/3dc87e5b/attachment.html>