On Sun, Apr 27, 2014 at 12:19 PM, Andreas Jaeger <a...@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@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev