change the example URLs in api-ref for Glance

Change all example urls in api-ref/source to
http://glance.openstack.example.org
and document about this standard URL format

Change-Id: I429c1e256fa3bfdc15adbee129b04ef9c028e82d
Closes-Bug: #1611490

api-ref/source/v1/images-images-v1.inc

@@ -71,7 +71,7 @@ Response Example (create with data)
      HTTP/1.1 201 Created
      Content-Type: application/json
      Content-Length: 491
-     Location: http://glance.example.com/v1/images/de2f2211-3ac7-4260-9142-41db0ecfb425
+     Location: http://glance.openstack.example.org/v1/images/de2f2211-3ac7-4260-9142-41db0ecfb425
      Etag: 7b1b10607acc1319506185e7227ca30d
      X-Openstack-Request-Id: req-70adeab4-740c-4db3-a002-fd1559ecf40f
      Date: Tue, 10 May 2016 21:41:41 GMT
@@ -91,7 +91,7 @@ with no headers specified and no data passed.  Here's the response:
      HTTP/1.1 201 Created
      Content-Type: application/json
      Content-Length: 447
-     Location: http://glance.example.com/v1/images/6b3ecfca-d445-4946-a8d1-c4938352b251
+     Location: http://glance.openstack.example.org/v1/images/6b3ecfca-d445-4946-a8d1-c4938352b251
      X-Openstack-Request-Id: req-db1ff3c7-3d4f-451f-9ef1-c414343f809d
      Date: Tue, 10 May 2016 21:35:14 GMT
 

api-ref/source/v2/metadefs-namespaces.inc

@@ -79,7 +79,7 @@ Response Example
     HTTP/1.1 201 Created
     Content-Length: 427
     Content-Type: application/json; charset=UTF-8
-    Location: http://glance.openstack.org/v2/metadefs/namespaces/FredCo::SomeCategory::Example
+    Location: http://glance.openstack.example.org/v2/metadefs/namespaces/FredCo::SomeCategory::Example
     X-Openstack-Request-Id: req-6d4a8ad2-c018-4bfc-8fe5-1a36c23c43eb
     Date: Thu, 19 May 2016 16:05:48 GMT
 

api-ref/source/v2/samples/task-create-request.json

@@ -1,7 +1,7 @@
 {
     "type": "import",
     "input": {
-        "import_from": "http://app.catalog.openstack.org/groovy-image",
+        "import_from": "http://app-catalog.openstack.example.org/groovy-image",
         "import_from_format": "qcow2",
         "image_properties": {
             "disk_format": "vhd",

api-ref/source/v2/samples/task-create-response.json

@@ -6,7 +6,7 @@
             "container_format": "ovf",
             "disk_format": "vhd"
         },
-        "import_from": "http://app.catalog.openstack.org/groovy-image",
+        "import_from": "http://app-catalog.openstack.example.org/groovy-image",
         "import_from_format": "qcow2"
     },
     "message": "",

api-ref/source/v2/samples/task-show-failure-response.json

@@ -7,7 +7,7 @@
             "container_format": "ovf",
             "disk_format": "vhd"
         },
-        "import_from": "http://app.catalog.openstack.org/groovy-image",
+        "import_from": "http://app-catalog.openstack.example.org/groovy-image",
         "import_from_format": "qcow2"
     },
     "message": "Task failed due to Internal Error",

doc/source/contributing/documentation.rst

@@ -1,6 +1,30 @@
 Documentation
 =============
 
+Tips for Doc Writers (and Developers, too!)
+-------------------------------------------
+
+Here are some useful tips about questions that come up a lot but aren't always
+easy to find answers to.
+
+* Make example URLs consistent
+
+  For consistency, example URLs for openstack components are in the form:
+
+  .. code::
+
+    project.openstack.example.org
+
+  So, for example, an example image-list call to Glance would use a URL
+  written like this:
+
+  .. code::
+
+    http://glance.openstack.example.org/v2/images
+
+Where to Contribute
+-------------------
+
 There are a few different kinds of documentation associated with Glance to
 which you may want to contribute: