Skip to content

Commit

Permalink
Fix rst formatting and cross-references
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@dhellmann
dhellmann authored and Lorin Hochstein committed Mar 6, 2012
1 parent 8979743 commit c16cd04
Show file tree
Hide file tree
Showing 31 changed files with 339 additions and 328 deletions.
1 change: 1 addition & 0 deletions .mailmap
View file
Expand Up @@ -21,6 +21,7 @@
<Dave.Walker@canonical.com> <DaveWalker@ubuntu.com> <Dave.Walker@canonical.com> <DaveWalker@ubuntu.com>
<derekh@redhat.com> <higginsd@gmail.com> <derekh@redhat.com> <higginsd@gmail.com>
<devin.carlen@gmail.com> <devcamcar@illian.local> <devin.carlen@gmail.com> <devcamcar@illian.local>
<doug.hellmann@dreamhost.com> <doug.hellmann@gmail.com>
<dprince@redhat.com> <dan.prince@rackspace.com> <dprince@redhat.com> <dan.prince@rackspace.com>
<edouard1.thuleau@orange.com> <thuleau@gmail.com> <edouard1.thuleau@orange.com> <thuleau@gmail.com>
<ewan.mellor@citrix.com> <emellor@silver> <ewan.mellor@citrix.com> <emellor@silver>
Expand Down
24 changes: 23 additions & 1 deletion doc/README.rst
View file
Expand Up @@ -2,7 +2,29 @@
Building the docs 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` Use `make`
Expand Down
2 changes: 1 addition & 1 deletion doc/generate_autodoc_index.sh
View file
Expand Up @@ -15,7 +15,7 @@ do
# and make sure to emit that many '=' under # and make sure to emit that many '=' under
# it to avoid heading format errors # it to avoid heading format errors
# in Sphinx. # in Sphinx.
let heading_len=$(echo "$heading" | wc -c) heading_len=$(echo "$heading" | wc -c)
underline=$(head -c $heading_len < /dev/zero | tr '\0' '=') underline=$(head -c $heading_len < /dev/zero | tr '\0' '=')
( cat <<EOF ( cat <<EOF
${heading} ${heading}
Expand Down
236 changes: 126 additions & 110 deletions doc/source/api_ext/ext_config_drive.rst
View file
Expand Up @@ -37,7 +37,8 @@ Doc Link (WADL)
http:// http://


Short Description 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 Sample Query Responses
---------------------- ----------------------
Expand All @@ -46,9 +47,16 @@ As shown below, responses to an EXTENSION query in XML or JSON provide basic inf


Extension Query Response: XML:: Extension Query Response: XML::


TBD

.. todo:: Provide example of extension query XML response.


Extension Query Response: JSON:: Extension Query Response: JSON::


TBD

.. todo:: Provide example of extension query JSON response.



Document Change History Document Change History
----------------------- -----------------------
Expand Down Expand Up @@ -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: 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:: 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" <?xml version="1.0" encoding="UTF-8"?>
flavorRef="52415800-8b69-11e0-9b19-734f1195ff37" <server xmlns="http://docs.openstack.org/compute/api/v1.1"
name="new-server-test" imageRef="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
config=drive="True" flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
> name="new-server-test"
<metadata> config=drive="True"
<meta key="My Server Name">Apache1</meta> >
</metadata> <metadata>
<personality> <meta key="My Server Name">Apache1</meta>
<file path="/etc/banner.txt"> </metadata>
ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp <personality>
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k <file path="/etc/banner.txt">
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
b25zLiINCg0KLVJpY2hhcmQgQmFjaA== dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
</file> c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
</personality> b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
</server> </file>

</personality>
Example XML with config_drive attribute is an imageRef:: </server>


<?xml version="1.0" encoding="UTF-8"?> Example XML with config_drive attribute is an imageRef:
<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" <?xml version="1.0" encoding="UTF-8"?>
name="new-server-test" <server xmlns="http://docs.openstack.org/compute/api/v1.1"
config_drive="http://servers.api.openstack.org/1234/images/52415800-8b69-1341-9b19-734f6f006e54" imageRef="http://servers.api.openstack.org/1234/images/
> 52415800-8b69-11e0-9b19-734f6f006e54"
<metadata> flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
<meta key="My Server Name">Apache1</meta> name="new-server-test"
</metadata> config_drive="http://servers.api.openstack.org/1234/images/52415800-8b69-1341-9b19-734f6f006e54"
<personality> >
<file path="/etc/banner.txt"> <metadata>
ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp <meta key="My Server Name">Apache1</meta>
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k </metadata>
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs <personality>
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g <file path="/etc/banner.txt">
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
b25zLiINCg0KLVJpY2hhcmQgQmFjaA== QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
</file> ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
</personality> dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
</server> c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6

b25zLiINCg0KLVJpY2hhcmQgQmFjaA==

</file>
Example JSON with config_drive attribute is true:: </personality>

</server>
{
"server" : {
"name" : "new-server-test", Example JSON with config_drive attribute is true:
"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" "server" : {
}, "name" : "new-server-test",
"personality" : [ "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
{ "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
"path" : "/etc/banner.txt", "config_drive" : "true",
"contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp "metadata" : {
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k "My Server Name" : "Apache1"
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs },
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g "personality" : [
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo {
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv "path" : "/etc/banner.txt",
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==" IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
} c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
] QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
}
]
}
} }
}

Example JSON with config_drive attribute is an imageRef:
Example JSON with config_drive attribute is an imageRef::

::
{
"server" : { {
"name" : "new-server-test", "server" : {
"imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54", "name" : "new-server-test",
"flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37", "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
"config_drive" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54", "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
"metadata" : { "config_drive" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
"My Server Name" : "Apache1" "metadata" : {
}, "My Server Name" : "Apache1"
"personality" : [ },
{ "personality" : [
"path" : "/etc/banner.txt", {
"contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp "path" : "/etc/banner.txt",
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==" c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
} b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
] }
]
}
} }
}
32 changes: 17 additions & 15 deletions doc/source/api_ext/ext_floating_ip_dns.rst
View file
@@ -1,5 +1,6 @@
About The Floating IP DNS Extension About The Floating IP DNS Extension
================================ ===================================

The Floating IP DNS extension provides an interface for managing DNS records associated with IP addresses 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. allocated by the Floating Ips extension. Requests are dispatched to a DNS driver selected at startup.


Expand Down Expand Up @@ -85,9 +86,10 @@ None


New Resources 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: # Sample Response:
{'domain_entries' : [ {'domain_entries' : [
Expand All @@ -97,9 +99,9 @@ Get a list of registered DNS Domains published by the DNS drivers:
{'domain': 'example.internal', 'scope': 'private', 'availability_zone': 'zone1'}]} {'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: # Sample body, public domain:
{'domain_entry' : {'domain_entry' :
Expand Down Expand Up @@ -130,18 +132,18 @@ Create or modify a DNS domain:
Failure Response Code: 403 (Insufficient permissions.) 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 Normal Response Code: 200
Failure Response Code: 404 (Domain to be deleted not found.) Failure Response Code: 404 (Domain to be deleted not found.)
Failure Response Code: 403 (Insufficient permissions to delete.) 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: # Sample body:
{ 'dns_entry' : { 'dns_entry' :
Expand All @@ -154,9 +156,9 @@ Create or modify a DNS entry:
'name' : 'instance1' }} '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: # Sample Response:
{ 'dns_entry' : { 'dns_entry' :
Expand All @@ -166,9 +168,9 @@ Find unique DNS entry for a given domain and name:
'name' : <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: # Sample Response:
{ 'dns_entries' : [ { 'dns_entries' : [
Expand All @@ -182,9 +184,9 @@ Find DNS entries for a given domain and ip:
'name' : 'example2' }]} '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 Normal Response Code: 200
Failure Response Code: 404 (Entry to be deleted not found) Failure Response Code: 404 (Entry to be deleted not found)
Expand Down

0 comments on commit c16cd04

Please sign in to comment.