Fix rst formatting and cross-references

blueprint sphinx-doc-cleanup bug 944385 - Fix formatting and markup issues that produce error messages - Update TOC lists for missing/new files - Fix a few links - Update instructions with dependencies for building the documentation - Updated base on review comments from oubiwann to fix trailing whitespace in modified files Change-Id: I589152bfab9c543d2b11fa8bed2344259aa90675
openstack · Mar 6, 2012 · c16cd04 · c16cd04
1 parent 8979743
commit c16cd04
Show file tree

Hide file tree

Showing 31 changed files with 339 additions and 328 deletions.
diff --git a/.mailmap b/.mailmap
@@ -21,6 +21,7 @@
 <Dave.Walker@canonical.com> <DaveWalker@ubuntu.com>
 <derekh@redhat.com> <higginsd@gmail.com>
 <devin.carlen@gmail.com> <devcamcar@illian.local>
+<doug.hellmann@dreamhost.com> <doug.hellmann@gmail.com>
 <dprince@redhat.com> <dan.prince@rackspace.com>
 <edouard1.thuleau@orange.com> <thuleau@gmail.com>
 <ewan.mellor@citrix.com> <emellor@silver>

diff --git a/doc/README.rst b/doc/README.rst
@@ -2,7 +2,29 @@
 Building the docs
 =================
 
-It is really easy. You'll need sphinx (the python one) and if you are using the virtualenv you'll need to install it in the virtualenv specifically so that it can load the nova modules.
+Dependencies
+============
+
+Sphinx_
+  You'll need sphinx (the python one) and if you are
+  using the virtualenv you'll need to install it in the virtualenv
+  specifically so that it can load the nova modules.
+
+  ::
+
+    pip install Sphinx
+
+Graphviz_
+  Some of the diagrams are generated using the ``dot`` language
+  from Graphviz.
+
+  ::
+
+    sudo apt-get install graphviz
+
+.. _Sphinx: http://sphinx.pocoo.org
+
+.. _Graphviz: http://www.graphviz.org/
 
 
 Use `make`

diff --git a/doc/generate_autodoc_index.sh b/doc/generate_autodoc_index.sh
@@ -15,7 +15,7 @@ do
   # and make sure to emit that many '=' under
   # it to avoid heading format errors
   # in Sphinx.
-  let heading_len=$(echo "$heading" | wc -c)
+  heading_len=$(echo "$heading" | wc -c)
   underline=$(head -c $heading_len < /dev/zero | tr '\0' '=')
   ( cat <<EOF
 ${heading}

diff --git a/doc/source/api_ext/ext_config_drive.rst b/doc/source/api_ext/ext_config_drive.rst
@@ -37,7 +37,8 @@ Doc Link (WADL)
 	http://
 
 Short Description
-	This extension enables the assignment of config-drives to a compute guest on instance create running in an OpenStack cloud.
+	This extension enables the assignment of config-drives to a
+	compute guest on instance create running in an OpenStack cloud.
 
 Sample Query Responses
 ----------------------
@@ -46,9 +47,16 @@ As shown below, responses to an EXTENSION query in XML or JSON provide basic inf
 
 Extension Query Response: XML::
 
+  TBD
+
+.. todo:: Provide example of extension query XML response.
 
 Extension Query Response: JSON::
 
+  TBD
+
+.. todo:: Provide example of extension query JSON response.
+
 
 Document Change History
 -----------------------
@@ -94,114 +102,122 @@ Changes to the Cloud Servers Specification
 In section 4.1.2 (Create Servers) of the API Specification: Examples 4.3 and 4.4 should optionally add the config-drive attribute as in the below examples:
 
 
-Example XML with config_drive attribute = True::
-
-<?xml version="1.0" encoding="UTF-8"?>
-<server xmlns="http://docs.openstack.org/compute/api/v1.1"
-        imageRef="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
-        flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
-        name="new-server-test"
-        config=drive="True"
-        >
-  <metadata>
-    <meta key="My Server Name">Apache1</meta>
-  </metadata>
-  <personality>
-    <file path="/etc/banner.txt">
-        ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
-        dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
-        IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
-        c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
-        QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
-        ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
-        dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
-        c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
-        b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
-    </file>
-  </personality>
-</server>
-
-Example XML with config_drive attribute is an imageRef::
-
-<?xml version="1.0" encoding="UTF-8"?>
-<server xmlns="http://docs.openstack.org/compute/api/v1.1"
-        imageRef="http://servers.api.openstack.org/1234/images/
-52415800-8b69-11e0-9b19-734f6f006e54"
-        flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
-        name="new-server-test"
-        config_drive="http://servers.api.openstack.org/1234/images/52415800-8b69-1341-9b19-734f6f006e54"
-        >
-  <metadata>
-    <meta key="My Server Name">Apache1</meta>
-  </metadata>
-  <personality>
-    <file path="/etc/banner.txt">
-        ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
-        dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
-        IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
-        c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
-        QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
-        ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
-        dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
-        c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
-        b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
-    </file>
-  </personality>
-</server>
-
-
-Example JSON with config_drive attribute is true::
-
-{
-    "server" : {
-        "name" : "new-server-test",
-        "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
-        "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
-        "config_drive" : "true",
-        "metadata" : {
-            "My Server Name" : "Apache1" 
-        },
-        "personality" : [
-            {
-                "path" : "/etc/banner.txt",
-                "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
- dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
- IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
- c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
- QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
- ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
- dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
- c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
- b25zLiINCg0KLVJpY2hhcmQgQmFjaA==" 
-            } 
-        ] 
+Example XML with config_drive attribute = True:
+
+::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <server xmlns="http://docs.openstack.org/compute/api/v1.1"
+            imageRef="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
+            flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
+            name="new-server-test"
+            config=drive="True"
+            >
+      <metadata>
+        <meta key="My Server Name">Apache1</meta>
+      </metadata>
+      <personality>
+        <file path="/etc/banner.txt">
+            ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
+            dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
+            IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
+            c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
+            QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
+            ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
+            dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
+            c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
+            b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
+        </file>
+      </personality>
+    </server>
+
+Example XML with config_drive attribute is an imageRef:
+
+::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <server xmlns="http://docs.openstack.org/compute/api/v1.1"
+            imageRef="http://servers.api.openstack.org/1234/images/
+    52415800-8b69-11e0-9b19-734f6f006e54"
+            flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
+            name="new-server-test"
+            config_drive="http://servers.api.openstack.org/1234/images/52415800-8b69-1341-9b19-734f6f006e54"
+            >
+      <metadata>
+        <meta key="My Server Name">Apache1</meta>
+      </metadata>
+      <personality>
+        <file path="/etc/banner.txt">
+            ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
+            dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
+            IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
+            c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
+            QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
+            ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
+            dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
+            c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
+            b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
+        </file>
+      </personality>
+    </server>
+
+
+Example JSON with config_drive attribute is true:
+
+::
+
+    {
+        "server" : {
+            "name" : "new-server-test",
+            "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
+            "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
+            "config_drive" : "true",
+            "metadata" : {
+                "My Server Name" : "Apache1"
+            },
+            "personality" : [
+                {
+                    "path" : "/etc/banner.txt",
+                    "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
+     dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
+     IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
+     c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
+     QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
+     ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
+     dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
+     c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
+     b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
+                }
+            ]
+        }
     }
-}
-
-Example JSON with config_drive attribute is an imageRef::
-
-{
-    "server" : {
-        "name" : "new-server-test",
-        "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
-        "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
-        "config_drive" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
-        "metadata" : {
-            "My Server Name" : "Apache1" 
-        },
-        "personality" : [
-            {
-                "path" : "/etc/banner.txt",
-                "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
- dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
- IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
- c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
- QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
- ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
- dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
- c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
- b25zLiINCg0KLVJpY2hhcmQgQmFjaA==" 
-            } 
-        ] 
+
+Example JSON with config_drive attribute is an imageRef:
+
+::
+
+    {
+        "server" : {
+            "name" : "new-server-test",
+            "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
+            "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
+            "config_drive" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
+            "metadata" : {
+                "My Server Name" : "Apache1"
+            },
+            "personality" : [
+                {
+                    "path" : "/etc/banner.txt",
+                    "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
+     dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
+     IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
+     c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
+     QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
+     ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
+     dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
+     c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
+     b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
+                }
+            ]
+        }
     }
-}
diff --git a/doc/source/api_ext/ext_floating_ip_dns.rst b/doc/source/api_ext/ext_floating_ip_dns.rst
@@ -1,5 +1,6 @@
 About The Floating IP DNS Extension
-================================
+===================================
+
 The Floating IP DNS extension provides an interface for managing DNS records associated with IP addresses
 allocated by the Floating Ips extension.  Requests are dispatched to a DNS driver selected at startup.
 
@@ -85,9 +86,10 @@ None
 
 New Resources
 -------------
-Get a list of registered DNS Domains published by the DNS drivers:
 
-        GET /v1.1/<tenant_id>/os-floating-ip-dns/
+Get a list of registered DNS Domains published by the DNS drivers::
+
+    GET /v1.1/<tenant_id>/os-floating-ip-dns/
 
     # Sample Response:
     {'domain_entries' : [
@@ -97,9 +99,9 @@ Get a list of registered DNS Domains published by the DNS drivers:
       {'domain': 'example.internal', 'scope': 'private', 'availability_zone': 'zone1'}]}
 
 
-Create or modify a DNS domain:
+Create or modify a DNS domain::
 
-        PUT /v1.1/<tenant_id>/os-floating-ip-dns/<domain>
+    PUT /v1.1/<tenant_id>/os-floating-ip-dns/<domain>
 
     # Sample body, public domain:
      {'domain_entry' :
@@ -130,18 +132,18 @@ Create or modify a DNS domain:
     Failure Response Code: 403 (Insufficient permissions.)
 
 
-Delete a DNS domain and all associated host entries:
+Delete a DNS domain and all associated host entries::
 
-DELETE /v1.1/<tenant_id>/os-floating-ip-dns/<domain>
+    DELETE /v1.1/<tenant_id>/os-floating-ip-dns/<domain>
 
     Normal Response Code: 200
     Failure Response Code: 404 (Domain to be deleted not found.)
     Failure Response Code: 403 (Insufficient permissions to delete.)
 
 
-Create or modify a DNS entry:
+Create or modify a DNS entry::
 
-        PUT /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
+    PUT /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
 
     # Sample body:
     { 'dns_entry' :
@@ -154,9 +156,9 @@ Create or modify a DNS entry:
         'name' : 'instance1' }}
 
 
-Find unique DNS entry for a given domain and name:
+Find unique DNS entry for a given domain and name::
 
-        GET /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
+    GET /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
 
     # Sample Response:
     { 'dns_entry' :
@@ -166,9 +168,9 @@ Find unique DNS entry for a given domain and name:
         'name' : <name> }}
 
 
-Find DNS entries for a given domain and ip:
+Find DNS entries for a given domain and ip::
 
-        GET /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries?ip=<ip>
+    GET /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries?ip=<ip>
 
     # Sample Response:
     { 'dns_entries' : [
@@ -182,9 +184,9 @@ Find DNS entries for a given domain and ip:
         'name' : 'example2' }]}
 
 
-Delete a DNS entry:
+Delete a DNS entry::
 
-DELETE /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
+    DELETE /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
 
     Normal Response Code: 200
     Failure Response Code: 404 (Entry to be deleted not found)