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
