<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Apr 27, 2014 at 12:19 PM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
The documentation team noticed that we have links in the version<br>
responses of several APIs that contain URLs that do not exist at all.<br>
<br>
For example, cinder includes a link to<br>
"<a href="http://jorgew.github.com/block-storage-api/content/os-block-storage-1.0.pdf" target="_blank">http://jorgew.github.com/block-storage-api/content/os-block-storage-1.0.pdf</a>"<br>
- and <a href="http://jorgew.github.com" target="_blank">jorgew.github.com</a> does not exist as host at all.<br>
<br>
The links we're concerned about are the links to WADL and PDF files.<br>
<br>
Even if we update the links to point to valid URLs, it takes away any<br>
flexibility for the documentation team to move files around on the<br>
server.<br>
<br>
Diane Fleming and myself therefore propose to remove all the WADL<br>
links completely and have the PDF links just point to<br>
<a href="http://docs.openstack.org" target="_blank">http://docs.openstack.org</a>. So, moving forward with Juno (unless this<br>
gets backported), the content would be valid.<br>
<br>
But what about existing installations that already include links? Some<br>
of the existing links work - or worked a few months ago before some<br>
files got moved around. We could try to fix <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a> so that<br>
the WADL and PDF links to <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a> (so, not the cinder example<br>
above) work somehow:<br>
1) Add redirects to current versions of WADL and PDF<br>
2) Add redirects to just <a href="http://docs.openstack.org/index.html" target="_blank">http://docs.openstack.org/index.html</a><br>
<br>
Since this affects several projects and is somehow user visible, we<br>
brought it up for discussion here. Note that some of these links seems<br>
to be broken for a very long time. The proposed changes do not break<br>
programs using the API - just users that look at the result of it in<br>
existing installations.<br>
<br>
So, my proposal would be:<br>
* Remove WADL links<br></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
* Have PDF links to go <a href="http://docs.openstack.org" target="_blank">http://docs.openstack.org</a></blockquote><div><br></div><div>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."</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
* For those current links to the site <a href="http://docs.openstack.org" target="_blank">http://docs.openstack.org</a>: Take<br>
care that they point either to a current file or get redirected to<br>
<a href="http://docs.openstack.org/index.html" target="_blank">http://docs.openstack.org/index.html</a><br>
<br>
What do you think?<br>
<br>
Andreas<br>
<br>
For more details see these bugs:<br>
cinder v2: <a href="https://bugs.launchpad.net/cinder/+bug/1313116" target="_blank">https://bugs.launchpad.net/cinder/+bug/1313116</a><br>
cinder v1: <a href="https://bugs.launchpad.net/cinder/+bug/1313118" target="_blank">https://bugs.launchpad.net/cinder/+bug/1313118</a><br>
nova v2 and v3: <a href="https://bugs.launchpad.net/nova/+bug/1313119" target="_blank">https://bugs.launchpad.net/nova/+bug/1313119</a><br>
identity v2.0 and v3: <a href="https://bugs.launchpad.net/keystone/+bug/1313127" target="_blank">https://bugs.launchpad.net/keystone/+bug/1313127</a><br>
<br>
A patch for Cinder is at <a href="https://review.openstack.org/90554" target="_blank">https://review.openstack.org/90554</a><br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</font></span></blockquote></div><br></div></div>