Merge lp:~jaypipes/glance/docs into lp:~hudson-openstack/glance/trunk

[Jay Pipes]

documentation cleanup and matching to other OpenStack projects. Glance is no longer the red-headed documentation stepchild in OpenStack...

[Jesse Andrews (anotherjesse)]

LGTM - merge reviews of docs are a great time to catch up on state of glance ;)

review: Approve

[Anne Gentle (annegentle)]

Just a couple of comments, other than "I love it!" Nicely done.

I'd remove "glance.openstack.org" in the examples of a vm store. Maybe use vmstore.openstack.org but avoid the use of glance.openstack.org since it's a clickable url that takes them to the doc site which is potentially confusion for the examples you're using.

Couple of nitpicks - ensure it's means "it is" and use periods at the end of bulleted list items.

If you want the CSS to match, you could use the Swift site as an example where the tweaks.css adds in OpenStack colors. Swift doesn't have the @OpenStack Twitter feed on the front page, Nova does. Feel free to copy the site you like best.

Should we track Glance.openstack.org with its own Google Analytics code? I can give the code to you if you want, or I can embed it after this gets merged.

review: Needs Fixing

[Jay Pipes (jaypipes)]

Hi Anne, thanks for the review!

> Just a couple of comments, other than "I love it!" Nicely done.
>
> I'd remove "glance.openstack.org" in the examples of a vm store. Maybe use
> vmstore.openstack.org but avoid the use of glance.openstack.org since it's a
> clickable url that takes them to the doc site which is potentially confusion
> for the examples you're using.

Done. s/glance.openstack.org/glance.example.com/g

> Couple of nitpicks - ensure it's means "it is" and use periods at the end of
> bulleted list items.

Done.

> If you want the CSS to match, you could use the Swift site as an example where
> the tweaks.css adds in OpenStack colors. Swift doesn't have the @OpenStack
> Twitter feed on the front page, Nova does. Feel free to copy the site you like
> best.

Done. Added both :)

> Should we track Glance.openstack.org with its own Google Analytics code? I can
> give the code to you if you want, or I can embed it after this gets merged.

Please feel free to do what you think is best here and to do that in a separate merge.

Thanks!
jay

[Rick Harris (rconradharris)]

Looks great! :)

review: Approve

[lp:~jaypipes/glance/docs]

28. By Rick Harris on 2010-12-23

Converts timestamp attributes to datetime objects before persisting.

Refactors image_update and image_create to use the same basic code.

[Anne Gentle (annegentle)]

Thanks for all the fixes. Coolio.

The Module Index link is broken, as you know. There's a similar (though maybe not related) bug on the nova.openstack.org site, https://bugs.launchpad.net/nova/+bug/693464 with broken links (URLs not being built quite right). Let's see if Monty or Chuck or someone knows of a fix and if that fix can apply here.

review: Approve

[lp:~jaypipes/glance/docs]

29. By Jay Pipes on 2010-12-23

documentation cleanup and matching to other OpenStack projects. Glance is no longer the red-headed documentation stepchild in OpenStack...

=== added file 'doc/Makefile'
--- doc/Makefile	1970-01-01 00:00:00 +0000
+++ doc/Makefile	2010-12-23 17:34:13 +0000
@@ -0,0 +1,97 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXSOURCE 	= source
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE)
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+.DEFAULT_GOAL 	= html
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+	-rm -rf nova.sqlite
+	if [ -f .autogenerated ] ; then \
+        cat .autogenerated | xargs rm ; \
+        rm .autogenerated ; \
+    fi
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nova.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc"
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

=== added file 'doc/source/_static/jquery.tweet.js'
--- doc/source/_static/jquery.tweet.js	1970-01-01 00:00:00 +0000
+++ doc/source/_static/jquery.tweet.js	2010-12-23 17:34:13 +0000
@@ -0,0 +1,154 @@
+(function($) {
+ 
+  $.fn.tweet = function(o){
+    var s = {
+      username: ["seaofclouds"],              // [string]   required, unless you want to display our tweets. :) it can be an array, just do ["username1","username2","etc"]
+      list: null,                              //[string]   optional name of list belonging to username
+      avatar_size: null,                      // [integer]  height and width of avatar if displayed (48px max)
+      count: 3,                               // [integer]  how many tweets to display?
+      intro_text: null,                       // [string]   do you want text BEFORE your your tweets?
+      outro_text: null,                       // [string]   do you want text AFTER your tweets?
+      join_text:  null,                       // [string]   optional text in between date and tweet, try setting to "auto"
+      auto_join_text_default: "i said,",      // [string]   auto text for non verb: "i said" bullocks
+      auto_join_text_ed: "i",                 // [string]   auto text for past tense: "i" surfed
+      auto_join_text_ing: "i am",             // [string]   auto tense for present tense: "i was" surfing
+      auto_join_text_reply: "i replied to",   // [string]   auto tense for replies: "i replied to" @someone "with"
+      auto_join_text_url: "i was looking at", // [string]   auto tense for urls: "i was looking at" http:...
+      loading_text: null,                     // [string]   optional loading text, displayed while tweets load
+      query: null                             // [string]   optional search query
+    };
+    
+    if(o) $.extend(s, o);
+    
+    $.fn.extend({
+      linkUrl: function() {
+        var returning = [];
+        var regexp = /((ftp|http|https):\/\/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?(\/|\/([\w#!:.?+=&%@!\-\/]))?)/gi;
+        this.each(function() {
+          returning.push(this.replace(regexp,"<a href=\"$1\">$1</a>"));
+        });
+        return $(returning);
+      },
+      linkUser: function() {
+        var returning = [];
+        var regexp = /[\@]+([A-Za-z0-9-_]+)/gi;
+        this.each(function() {
+          returning.push(this.replace(regexp,"<a href=\"http://twitter.com/$1\">@$1</a>"));
+        });
+        return $(returning);
+      },
+      linkHash: function() {
+        var returning = [];
+        var regexp = / [\#]+([A-Za-z0-9-_]+)/gi;
+        this.each(function() {
+          returning.push(this.replace(regexp, ' <a href="http://search.twitter.com/search?q=&tag=$1&lang=all&from='+s.username.join("%2BOR%2B")+'">#$1</a>'));
+        });
+        return $(returning);
+      },
+      capAwesome: function() {
+        var returning = [];
+        this.each(function() {
+          returning.push(this.replace(/\b(awesome)\b/gi, '<span class="awesome">$1</span>'));
+        });
+        return $(returning);
+      },
+      capEpic: function() {
+        var returning = [];
+        this.each(function() {
+          returning.push(this.replace(/\b(epic)\b/gi, '<span class="epic">$1</span>'));
+        });
+        return $(returning);
+      },
+      makeHeart: function() {
+        var returning = [];
+        this.each(function() {
+          returning.push(this.replace(/(&lt;)+[3]/gi, "<tt class='heart'>&#x2665;</tt>"));
+        });
+        return $(returning);
+      }
+    });
+
+    function relative_time(time_value) {
+      var parsed_date = Date.parse(time_value);
+      var relative_to = (arguments.length > 1) ? arguments[1] : new Date();
+      var delta = parseInt((relative_to.getTime() - parsed_date) / 1000);
+      var pluralize = function (singular, n) {
+        return '' + n + ' ' + singular + (n == 1 ? '' : 's');
+      };
+      if(delta < 60) {
+      return 'less than a minute ago';
+      } else if(delta < (45*60)) {
+      return 'about ' + pluralize("minute", parseInt(delta / 60)) + ' ago';
+      } else if(delta < (24*60*60)) {
+      return 'about ' + pluralize("hour", parseInt(delta / 3600)) + ' ago';
+      } else {
+      return 'about ' + pluralize("day", parseInt(delta / 86400)) + ' ago';
+      }
+    }
+
+    function build_url() {
+      var proto = ('https:' == document.location.protocol ? 'https:' : 'http:');
+      if (s.list) {
+        return proto+"//api.twitter.com/1/"+s.username[0]+"/lists/"+s.list+"/statuses.json?per_page="+s.count+"&callback=?";
+      } else if (s.query == null && s.username.length == 1) {
+        return proto+'//twitter.com/status/user_timeline/'+s.username[0]+'.json?count='+s.count+'&callback=?';
+      } else {
+        var query = (s.query || 'from:'+s.username.join('%20OR%20from:'));
+        return proto+'//search.twitter.com/search.json?&q='+query+'&rpp='+s.count+'&callback=?';
+      }
+    }
+
+    return this.each(function(){
+      var list = $('<ul class="tweet_list">').appendTo(this);
+      var intro = '<p class="tweet_intro">'+s.intro_text+'</p>';
+      var outro = '<p class="tweet_outro">'+s.outro_text+'</p>';
+      var loading = $('<p class="loading">'+s.loading_text+'</p>');
+
+      if(typeof(s.username) == "string"){
+        s.username = [s.username];
+      }
+
+      if (s.loading_text) $(this).append(loading);
+      $.getJSON(build_url(), function(data){
+        if (s.loading_text) loading.remove();
+        if (s.intro_text) list.before(intro);
+        $.each((data.results || data), function(i,item){
+          // auto join text based on verb tense and content
+          if (s.join_text == "auto") {
+            if (item.text.match(/^(@([A-Za-z0-9-_]+)) .*/i)) {
+              var join_text = s.auto_join_text_reply;
+            } else if (item.text.match(/(^\w+:\/\/[A-Za-z0-9-_]+\.[A-Za-z0-9-_:%&\?\/.=]+) .*/i)) {
+              var join_text = s.auto_join_text_url;
+            } else if (item.text.match(/^((\w+ed)|just) .*/im)) {
+              var join_text = s.auto_join_text_ed;
+            } else if (item.text.match(/^(\w*ing) .*/i)) {
+              var join_text = s.auto_join_text_ing;
+            } else {
+              var join_text = s.auto_join_text_default;
+            }
+          } else {
+            var join_text = s.join_text;
+          };
+
+          var from_user = item.from_user || item.user.screen_name;
+          var profile_image_url = item.profile_image_url || item.user.profile_image_url;
+          var join_template = '<span class="tweet_join"> '+join_text+' </span>';
+          var join = ((s.join_text) ? join_template : ' ');
+          var avatar_template = '<a class="tweet_avatar" href="http://twitter.com/'+from_user+'"><img src="'+profile_image_url+'" height="'+s.avatar_size+'" width="'+s.avatar_size+'" alt="'+from_user+'\'s avatar" title="'+from_user+'\'s avatar" border="0"/></a>';
+          var avatar = (s.avatar_size ? avatar_template : '');
+          var date = '<a href="http://twitter.com/'+from_user+'/statuses/'+item.id+'" title="view tweet on twitter">'+relative_time(item.created_at)+'</a>';
+          var text = '<span class="tweet_text">' +$([item.text]).linkUrl().linkUser().linkHash().makeHeart().capAwesome().capEpic()[0]+ '</span>';
+
+          // until we create a template option, arrange the items below to alter a tweet's display.
+          list.append('<li>' + avatar + date + join + text + '</li>');
+
+          list.children('li:first').addClass('tweet_first');
+          list.children('li:odd').addClass('tweet_even');
+          list.children('li:even').addClass('tweet_odd');
+        });
+        if (s.outro_text) list.after(outro);
+      });
+
+    });
+  };
+})(jQuery);
\ No newline at end of file

=== added file 'doc/source/_static/tweaks.css'
--- doc/source/_static/tweaks.css	1970-01-01 00:00:00 +0000
+++ doc/source/_static/tweaks.css	2010-12-23 17:34:13 +0000
@@ -0,0 +1,65 @@
+ul.todo_list {
+    list-style-type: none;
+    margin: 0;
+    padding: 0;
+}
+
+ul.todo_list li {
+    display: block;
+    margin: 0;
+    padding: 7px 0;
+    border-top: 1px solid #eee;
+}
+
+ul.todo_list li p {
+    display: inline;
+}
+
+ul.todo_list li p.link {
+    font-weight: bold;
+}
+
+ul.todo_list li p.details {
+    font-style: italic;
+}
+
+ul.todo_list li {
+}
+
+div.admonition {
+    border: 1px solid #8F1000;
+}
+
+div.admonition p.admonition-title {
+    background-color: #8F1000;
+    border-bottom: 1px solid #8E8E8E;
+}
+
+a {
+	color: #CF2F19;
+}
+
+div.related ul li a {
+	color: #CF2F19;
+}
+
+div.sphinxsidebar h4 {
+	background-color:#8E8E8E;
+	border:1px solid #255E6E;
+	color:white;
+	font-size:1em;
+	margin:1em 0 0.5em;
+	padding:0.1em 0 0.1em 0.5em;
+}
+
+em {
+    font-style: normal;
+}
+
+table.docutils {
+	font-size: 11px;
+}
+
+a tt {
+	color:#CF2F19;
+}
\ No newline at end of file

=== added directory 'doc/source/_templates'
=== added file 'doc/source/_templates/.placeholder'
=== added directory 'doc/source/_theme'
=== added file 'doc/source/_theme/layout.html'
--- doc/source/_theme/layout.html	1970-01-01 00:00:00 +0000
+++ doc/source/_theme/layout.html	2010-12-23 17:34:13 +0000
@@ -0,0 +1,86 @@
+{% extends "sphinxdoc/layout.html" %}
+{% set css_files = css_files + ['_static/tweaks.css'] %}
+{% set script_files = script_files + ['_static/jquery.tweet.js'] %}
+{% block extrahead %}
+    <script type='text/javascript'>
+        $(document).ready(function(){
+            $("#twitter_feed").tweet({
+                username: "openstack",
+                query: "from:openstack",
+                avatar_size: 32,
+                count: 10,
+                loading_text: "loading tweets..."
+            });
+        });
+    </script>
+{% endblock %}
+
+{%- macro sidebar() %}
+      {%- if not embedded %}{% if not theme_nosidebar|tobool %}
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+          {%- block sidebarlogo %}
+          {%- if logo %}
+            <p class="logo"><a href="{{ pathto(master_doc) }}">
+              <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+            </a></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebartoc %}
+          {%- if display_toc %}
+            <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+            {{ toc }}
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebarrel %}
+          {%- if prev %}
+            <h4>{{ _('Previous topic') }}</h4>
+            <p class="topless"><a href="{{ prev.link|e }}"
+                                  title="{{ _('previous chapter') }}">{{ prev.title }}</a></p>
+          {%- endif %}
+          {%- if next %}
+            <h4>{{ _('Next topic') }}</h4>
+            <p class="topless"><a href="{{ next.link|e }}"
+                                  title="{{ _('next chapter') }}">{{ next.title }}</a></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebarsourcelink %}
+          {%- if show_source and has_source and sourcename %}
+            <h3>{{ _('This Page') }}</h3>
+            <ul class="this-page-menu">
+              <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+                     rel="nofollow">{{ _('Show Source') }}</a></li>
+            </ul>
+          {%- endif %}
+          {%- endblock %}
+          {%- if customsidebar %}
+          {% include customsidebar %}
+          {%- endif %}
+          {%- block sidebarsearch %}
+          {%- if pagename != "search" %}
+          <div id="searchbox" style="display: none">
+            <h3>{{ _('Quick search') }}</h3>
+              <form class="search" action="{{ pathto('search') }}" method="get">
+                <input type="text" name="q" size="18" />
+                <input type="submit" value="{{ _('Go') }}" />
+                <input type="hidden" name="check_keywords" value="yes" />
+                <input type="hidden" name="area" value="default" />
+              </form>
+              <p class="searchtip" style="font-size: 90%">
+              {{ _('Enter search terms or a module, class or function name.') }}
+              </p>
+          </div>
+          <script type="text/javascript">$('#searchbox').show(0);</script>
+          {%- endif %}
+
+          {%- if pagename == "index" %}
+                <h3>{{ _('Twitter Feed') }}</h3>
+                <div id="twitter_feed" class='twitter_feed'></div>
+          {%- endif %}
+
+
+          {%- endblock %}
+        </div>
+      </div>
+      {%- endif %}{% endif %}
+{%- endmacro %}

=== added file 'doc/source/_theme/theme.conf'
--- doc/source/_theme/theme.conf	1970-01-01 00:00:00 +0000
+++ doc/source/_theme/theme.conf	2010-12-23 17:34:13 +0000
@@ -0,0 +1,5 @@
+[theme]
+inherit = sphinxdoc
+stylesheet = sphinxdoc.css
+pygments_style = friendly
+

=== added file 'doc/source/client.rst'
--- doc/source/client.rst	1970-01-01 00:00:00 +0000
+++ doc/source/client.rst	2010-12-23 17:34:13 +0000
@@ -0,0 +1,231 @@
+..
+      Copyright 2010 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Using Glance Programmatically with Glance's Client
+==================================================
+
+While it is perfectly acceptable to issue HTTP requests directly to Glance
+via its RESTful API, sometimes it is better to be able to access and modify
+image resources via a client class that removes some of the complexity and
+tedium of dealing with raw HTTP requests.
+
+Glance includes a client class for just this purpose. You can retrieve
+metadata about an image, change metadata about an image, remove images, and
+of course retrieve an image itself via this client class.
+
+Below are some examples of using Glance's Client class.  We assume that
+there is a Glance server running at the address `glance.example.com`
+on port `9292`.
+
+Requesting a List of Public VM Images
+-------------------------------------
+
+We want to see a list of available virtual machine images that the Glance
+server knows about.
+
+Using Glance's Client, we can do this using the following code::
+
+  from glance import client
+
+  c = client.Client("glance.example.com", 9292)
+
+  print c.get_images()
+
+
+Requesting Detailed Metadata on Public VM Images
+------------------------------------------------
+
+We want to see more detailed information on available virtual machine images
+that the Glance server knows about.
+
+Using Glance's Client, we can do this using the following code::
+
+  from glance import client
+
+  c = client.Client("glance.example.com", 9292)
+
+  print c.get_images_detailed()
+
+
+Requesting Detailed Metadata on a Specific Image
+------------------------------------------------
+
+We want to see detailed information for a specific virtual machine image
+that the Glance server knows about.
+
+We have queried the Glance server for a list of public images and the
+data returned includes the `uri` field for each available image. This
+`uri` field value contains the exact location needed to get the metadata
+for a specific image.
+
+Continuing the example from above, in order to get metadata about the
+first public image returned, we can use the following code::
+
+  from glance import client
+
+  c = client.Client("glance.example.com", 9292)
+
+  print c.get_image_meta("http://glance.example.com/images/1")
+
+
+Retrieving a Virtual Machine Image
+----------------------------------
+
+We want to retrieve that actual raw data for a specific virtual machine image
+that the Glance server knows about.
+
+We have queried the Glance server for a list of public images and the
+data returned includes the `uri` field for each available image. This
+`uri` field value contains the exact location needed to get the metadata
+for a specific image.
+
+Continuing the example from above, in order to get both the metadata about the
+first public image returned and its image data, we can use the following code::
+
+  from glance import client
+
+  c = client.Client("glance.example.com", 9292)
+
+  meta, image_file = c.get_image("http://glance.example.com/images/1")
+
+  print meta
+
+  f = open('some_local_file', 'wb')
+  for chunk in image_file:
+      f.write(chunk)
+  f.close()
+
+Note that the return from Client.get_image() is a tuple of (`metadata`, `file`)
+where `metadata` is a mapping of metadata about the image and `file` is a
+generator that yields chunks of image data.
+
+Adding a New Virtual Machine Image
+----------------------------------
+
+We have created a new virtual machine image in some way (created a
+"golden image" or snapshotted/backed up an existing image) and we
+wish to do two things:
+
+ * Store the disk image data in Glance
+ * Store metadata about this image in Glance
+
+We can do the above two activities in a single call to the Glance client.
+Assuming, like in the examples above, that a Glance API server is running
+at `glance.example.com`, we issue a call to `glance.client.Client.add_image`.
+
+The method signature is as follows::
+
+  glance.client.Client.add_image(image_meta, image_data=None)
+
+The `image_meta` argument is a mapping containing various image metadata. The
+`image_data` argument is the disk image data.
+
+The list of metadata that `image_meta` can contain are listed below.
+
+ * `name`
+
+   This key/value is required. Its value should be the name of the image.
+
+   Note that the name of an image *is not unique to a Glance node*. It
+   would be an unrealistic expectation of users to know all the unique
+   names of all other user's images.
+
+ * `id`
+
+   This key/value is optional. 
+   
+   When present, Glance will use the supplied identifier for the image.
+   If the identifier already exists in that Glance node, then a
+   `glance.common.exception.Duplicate` will be raised.
+
+   When this key/value is *not* present, Glance will generate an identifier
+   for the image and return this identifier in the response (see below)
+
+ * `store`
+
+   This key/value is optional. Valid values are one of `file` or `swift`
+
+   When present, Glance will attempt to store the disk image data in the
+   backing store indicated by the value. If the Glance node does not support
+   the backing store, Glance will raise a `glance.common.exception.BadRequest`
+
+   When not present, Glance will store the disk image data in the backing
+   store that is marked default. See the configuration option `default_store`
+   for more information.
+
+ * `type`
+
+   This key/values is required. Valid values are one of `kernel`, `machine`,
+   `raw`, or `ramdisk`.
+
+ * `size`
+
+   This key/value is optional.
+
+   When present, Glance assumes that the expected size of the request body
+   will be the value. If the length in bytes of the request body *does not
+   match* the value, Glance will raise a `glance.common.exception.BadRequest`
+
+   When not present, Glance will calculate the image's size based on the size
+   of the request body.
+
+ * `is_public`
+
+   This key/value is optional.
+
+   When present, Glance converts the value to a boolean value, so "on, 1, true"
+   are all true values. When true, the image is marked as a public image,
+   meaning that any user may view its metadata and may read the disk image from
+   Glance.
+
+   When not present, the image is assumed to be *not public* and specific to
+   a user.
+
+ * `properties`
+
+   This key/value is optional.
+
+   When present, the value is assumed to be a mapping of free-form key/value
+   attributes to store with the image.
+
+   For example, if the following is the value of the `properties` key in the
+   `image_meta` argument::
+
+      {'distro': 'Ubuntu 10.10'}
+
+   Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
+   image in Glance.
+
+   There is no limit on the number of free-form key/value attributes that can
+   be attached to the image with `properties`.  However, keep in mind that there
+   is a 8K limit on the size of all HTTP headers sent in a request and this
+   number will effectively limit the number of image properties.
+
+As a complete example, the following code would add a new machine image to
+Glance::
+
+  from glance.client import Client
+
+  c = Client("glance.example.com", 9292)
+
+  meta = {'name': 'Ubuntu 10.10 5G',
+          'type': 'machine',
+          'is_public': True,
+          'properties': {'distro': 'Ubuntu 10.10'}}
+
+  new_meta = c.add_image(meta, open('/path/to/image.tar.gz'))
+
+  print 'Stored image. Got identifier: %s' % new_meta['id']

=== added file 'doc/source/community.rst'
--- doc/source/community.rst	1970-01-01 00:00:00 +0000
+++ doc/source/community.rst	2010-12-23 17:34:13 +0000
@@ -0,0 +1,83 @@
+..
+      Copyright 2010 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Getting Involved
+================
+
+The Glance community is a very friendly group and there are places online to join in with the 
+community. Feel free to ask questions. This document points you to some of the places where you can
+communicate with people.
+
+How to Join the OpenStack Community
+-----------------------------------
+
+Our community welcomes all people interested in open source cloud computing, and there are no formal
+membership requirements. The best way to join the community is to talk with others online or at a meetup
+and offer contributions through Launchpad, the wiki, or blogs. We welcome all types of contributions, 
+from blueprint designs to documentation to testing to deployment scripts. 
+
+Contributing Code
+-----------------
+
+To contribute code, sign up for a Launchpad account and sign a contributor license agreement,
+available on the `<http://wiki.openstack.org/CLA>`_. Once the CLA is signed you 
+can contribute code through the Bazaar version control system which is related to your Launchpad account.
+
+#openstack on Freenode IRC Network
+----------------------------------
+
+There is a very active chat channel at `<irc://freenode.net/#openstack>`_.  This
+is usually the best place to ask questions and find your way around. IRC stands for Internet Relay
+Chat and it is a way to chat online in real time. You can also ask a question and come back to the 
+log files to read the answer later. Logs for the #openstack IRC channel are stored at 
+`<http://eavesdrop.openstack.org/irclogs/>`_.
+
+OpenStack Wiki
+--------------
+
+The wiki is a living source of knowledge.  It is edited by the community, and
+has collections of links and other sources of information. Typically the pages are a good place
+to write drafts for specs or documentation, describe a blueprint, or collaborate with others.
+
+`OpenStack Wiki <http://wiki.openstack.org/>`_
+
+Glance on Launchpad
+-------------------
+
+Launchpad is a code hosting service that hosts the Glance source code. From
+Launchpad you can report bugs, ask questions, and register blueprints (feature requests). 
+
+* `Learn about how to use bzr with launchpad <http://wiki.openstack.org/LifeWithBzrAndLaunchpad>`_
+* `Launchpad Glance Page <http://launchpad.net/glance>`_
+
+OpenStack Blog
+--------------
+
+The OpenStack blog includes a weekly newsletter that aggregates OpenStack news
+from around the internet, as well as providing inside information on upcoming
+events and posts from OpenStack contributors.
+
+`OpenStack Blog <http://openstack.org/blog>`_
+
+See also: `Planet OpenStack <http://planet.openstack.org/>`_, aggregating blogs
+about OpenStack from around the internet into a single feed. If you'd like to contribute to this blog
+aggregation with your blog posts, there are instructions for `adding your blog <http://wiki.openstack.org/AddingYourBlog>`_.
+
+Twitter
+-------
+
+Because all the cool kids do it: `@openstack <http://twitter.com/openstack>`_. Also follow the 
+`#openstack <http://search.twitter.com/search?q=%23openstack>`_ tag for relevant tweets.

=== modified file 'doc/source/conf.py'
--- doc/source/conf.py	2010-09-26 07:25:34 +0000
+++ doc/source/conf.py	2010-12-23 17:34:13 +0000
@@ -31,8 +31,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.append([os.path.abspath('../teller'),
-    os.path.abspath('../parallax'),
+sys.path.append([os.path.abspath('../glance'),
     os.path.abspath('..'),
     os.path.abspath('../bin')
     ])
@@ -45,7 +44,11 @@
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = []
+if os.getenv('HUDSON_PUBLISH_DOCS'):
+  templates_path = ['_ga', '_templates']
+else:
+  templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -104,14 +107,15 @@
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-modindex_common_prefix = ['parallax.','teller.']
+modindex_common_prefix = ['glance.']
 
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme_path = ["."]
+html_theme = '_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -119,7 +123,7 @@
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+#html_theme_path = ['_theme']
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".

=== added file 'doc/source/glanceapi.rst'
--- doc/source/glanceapi.rst	1970-01-01 00:00:00 +0000
+++ doc/source/glanceapi.rst	2010-12-23 17:34:13 +0000
@@ -0,0 +1,294 @@
+..
+      Copyright 2010 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+The Glance REST API
+===================
+
+Glance has a RESTful API that exposes both metadata about registered virtual
+machine images and the image data itself.
+
+A host that runs the `bin/glance-api` service is said to be a *Glance API
+Server*.
+
+Assume there is a Glance API server running at the URL
+http://glance.example.com. 
+
+Let's walk through how a user might request information from this server.
+
+Requesting a List of Public VM Images
+-------------------------------------
+
+We want to see a list of available virtual machine images that the Glance
+server knows about.
+
+We issue a `GET` request to http://glance.example.com/images/ to retrieve
+this list of available *public* images. The data is returned as a JSON-encoded
+mapping in the following format::
+
+  {'images': [
+    {'uri': 'http://glance.example.com/images/1',
+     'name': 'Ubuntu 10.04 Plain',
+     'type': 'kernel',
+     'size': '5368709120'}
+    ...]}
+
+Notes:
+
+ * All images returned from the above `GET` request are *public* images
+
+
+Requesting Detailed Metadata on Public VM Images
+------------------------------------------------
+
+We want to see more detailed information on available virtual machine images
+that the Glance server knows about.
+
+We issue a `GET` request to http://glance.example.com/images/detail to
+retrieve this list of available *public* images. The data is returned as a
+JSON-encoded mapping in the following format::
+
+  {'images': [
+    {'uri': 'http://glance.example.com/images/1',
+     'name': 'Ubuntu 10.04 Plain 5GB',
+     'type': 'kernel',
+     'size': '5368709120',
+     'store': 'swift',
+     'created_at': '2010-02-03 09:34:01',
+     'updated_at': '2010-02-03 09:34:01',
+     'deleted_at': '',
+     'status': 'available',
+     'is_public': True,
+     'properties': {'distro': 'Ubuntu 10.04 LTS'}},
+    ...]}
+
+Notes:
+
+ * All images returned from the above `GET` request are *public* images
+ * All timestamps returned are in UTC
+ * The `updated_at` timestamp is the timestamp when an image's metadata
+   was last updated, not its image data, as all image data is immutable
+   once stored in Glance
+ * The `properties` field is a mapping of free-form key/value pairs that
+   have been saved with the image metadata
+
+
+Requesting Detailed Metadata on a Specific Image
+------------------------------------------------
+
+We want to see detailed information for a specific virtual machine image
+that the Glance server knows about.
+
+We have queried the Glance server for a list of public images and the
+data returned includes the `uri` field for each available image. This
+`uri` field value contains the exact location needed to get the metadata
+for a specific image.
+
+Continuing the example from above, in order to get metadata about the
+first public image returned, we can issue a `HEAD` request to the Glance
+server for the image's URI.
+
+We issue a `HEAD` request to http://glance.example.com/images/1 to
+retrieve complete metadata for that image. The metadata is returned as a
+set of HTTP headers that begin with the prefix `x-image-meta-`. The
+following shows an example of the HTTP headers returned from the above
+`HEAD` request::
+
+  x-image-meta-uri              http://glance.example.com/images/1
+  x-image-meta-name             Ubuntu 10.04 Plain 5GB
+  x-image-meta-type             kernel
+  x-image-meta-size             5368709120
+  x-image-meta-store            swift
+  x-image-meta-created_at       2010-02-03 09:34:01
+  x-image-meta-updated_at       2010-02-03 09:34:01
+  x-image-meta-deleted_at       
+  x-image-meta-status           available
+  x-image-meta-is_public        True
+  x-image-meta-property-distro  Ubuntu 10.04 LTS
+
+Notes:
+
+ * All timestamps returned are in UTC
+ * The `x-image-meta-updated_at` timestamp is the timestamp when an
+   image's metadata was last updated, not its image data, as all 
+   image data is immutable once stored in Glance
+ * There may be multiple headers that begin with the prefix
+   `x-image-meta-property-`.  These headers are free-form key/value pairs
+   that have been saved with the image metadata. The key is the string
+   after `x-image-meta-property-` and the value is the value of the header
+
+
+Retrieving a Virtual Machine Image
+----------------------------------
+
+We want to retrieve that actual raw data for a specific virtual machine image
+that the Glance server knows about.
+
+We have queried the Glance server for a list of public images and the
+data returned includes the `uri` field for each available image. This
+`uri` field value contains the exact location needed to get the metadata
+for a specific image.
+
+Continuing the example from above, in order to get metadata about the
+first public image returned, we can issue a `HEAD` request to the Glance
+server for the image's URI.
+
+We issue a `GET` request to http://glance.example.com/images/1 to
+retrieve metadata for that image as well as the image itself encoded
+into the response body.
+
+The metadata is returned as a set of HTTP headers that begin with the
+prefix `x-image-meta-`. The following shows an example of the HTTP headers
+returned from the above `GET` request::
+
+  x-image-meta-uri              http://glance.example.com/images/1
+  x-image-meta-name             Ubuntu 10.04 Plain 5GB
+  x-image-meta-type             kernel
+  x-image-meta-size             5368709120
+  x-image-meta-store            swift
+  x-image-meta-created_at       2010-02-03 09:34:01
+  x-image-meta-updated_at       2010-02-03 09:34:01
+  x-image-meta-deleted_at       
+  x-image-meta-status           available
+  x-image-meta-is_public        True
+  x-image-meta-property-distro  Ubuntu 10.04 LTS
+
+Notes:
+
+ * All timestamps returned are in UTC
+ * The `x-image-meta-updated_at` timestamp is the timestamp when an
+   image's metadata was last updated, not its image data, as all 
+   image data is immutable once stored in Glance
+ * There may be multiple headers that begin with the prefix
+   `x-image-meta-property-`.  These headers are free-form key/value pairs
+   that have been saved with the image metadata. The key is the string
+   after `x-image-meta-property-` and the value is the value of the header
+ * The response's `Content-Length` header shall be equal to the value of
+   the `x-image-meta-size` header
+ * The image data itself will be the body of the HTTP response returned
+   from the request, which will have content-type of
+   `application/octet-stream`.
+
+
+Adding a New Virtual Machine Image
+----------------------------------
+
+We have created a new virtual machine image in some way (created a
+"golden image" or snapshotted/backed up an existing image) and we
+wish to do two things:
+
+ * Store the disk image data in Glance
+ * Store metadata about this image in Glance
+
+We can do the above two activities in a single call to the Glance API.
+Assuming, like in the examples above, that a Glance API server is running
+at `glance.example.com`, we issue a `POST` request to add an image to
+Glance::
+
+  POST http://glance.example.com/images/
+
+The metadata about the image is sent to Glance in HTTP headers. The body
+of the HTTP request to the Glance API will be the MIME-encoded disk
+image data.
+
+
+Adding Image Metadata in HTTP Headers
+*************************************
+
+Glance will view as image metadata any HTTP header that it receives in a
+`POST` request where the header key is prefixed with the strings
+`x-image-meta-` and `x-image-meta-property-`.
+
+The list of metadata headers that Glance accepts are listed below.
+
+ * `x-image-meta-name`
+
+   This header is required. Its value should be the name of the image.
+
+   Note that the name of an image *is not unique to a Glance node*. It
+   would be an unrealistic expectation of users to know all the unique
+   names of all other user's images.
+
+ * `x-image-meta-id`
+
+   This header is optional. 
+   
+   When present, Glance will use the supplied identifier for the image.
+   If the identifier already exists in that Glance node, then a
+   `409 Conflict` will be returned by Glance.
+
+   When this header is *not* present, Glance will generate an identifier
+   for the image and return this identifier in the response (see below)
+
+ * `x-image-meta-store`
+
+   This header is optional. Valid values are one of `file` or `swift`
+
+   When present, Glance will attempt to store the disk image data in the
+   backing store indicated by the value of the header. If the Glance node
+   does not support the backing store, Glance will return a `400 Bad Request`.
+
+   When not present, Glance will store the disk image data in the backing
+   store that is marked default. See the configuration option `default_store`
+   for more information.
+
+ * `x-image-meta-type`
+
+   This header is required. Valid values are one of `kernel`, `machine`, `raw`,
+   or `ramdisk`.
+
+ * `x-image-meta-size`
+
+   This header is optional.
+
+   When present, Glance assumes that the expected size of the request body
+   will be the value of this header. If the length in bytes of the request
+   body *does not match* the value of this header, Glance will return a
+   `400 Bad Request`.
+
+   When not present, Glance will calculate the image's size based on the size
+   of the request body.
+
+ * `x-image-meta-is_public`
+
+   This header is optional.
+
+   When present, Glance converts the value of the header to a boolean value,
+   so "on, 1, true" are all true values. When true, the image is marked as
+   a public image, meaning that any user may view its metadata and may read
+   the disk image from Glance.
+
+   When not present, the image is assumed to be *not public* and specific to
+   a user.
+
+ * `x-image-meta-property-*`
+
+   When Glance receives any HTTP header whose key begins with the string prefix
+   `x-image-meta-property-`, Glance adds the key and value to a set of custom,
+   free-form image properties stored with the image.  The key is the
+   lower-cased string following the prefix `x-image-meta-property-` with dashes
+   and punctuation replaced with underscores.
+
+   For example, if the following HTTP header were sent::
+
+      x-image-meta-property-distro  Ubuntu 10.10
+
+   Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
+   image in Glance.
+
+   There is no limit on the number of free-form key/value attributes that can
+   be attached to the image.  However, keep in mind that the 8K limit on the
+   size of all HTTP headers sent in a request will effectively limit the number
+   of image properties.

=== added file 'doc/source/identifiers.rst'
--- doc/source/identifiers.rst	1970-01-01 00:00:00 +0000
+++ doc/source/identifiers.rst	2010-12-23 17:34:13 +0000
@@ -0,0 +1,27 @@
+..
+      Copyright 2010 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Image Identifiers
+=================
+
+Images are uniquely identified by way of a URI that
+matches the following signature::
+
+  <Glance Server Location>/images/<ID>
+
+where `<Glance Server Location>` is the resource location of the Glance service
+that knows about an image, and `<ID>` is the image's identifier that is
+*unique to that Glance server*.

=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2010-12-20 17:12:46 +0000
+++ doc/source/index.rst	2010-12-23 17:34:13 +0000
@@ -1,7 +1,18 @@
-.. Glance documentation master file, created by
-   sphinx-quickstart on Tue May 18 13:50:15 2010.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+..
+      Copyright 2010 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
 
 Welcome to Glance's documentation!
 ==================================
@@ -14,555 +25,52 @@
 locations from simple filesystems to object-storage systems like the
 OpenStack Swift project.
 
-.. toctree::
-    :maxdepth: 1
-
-Overview
+Glance, as with all OpenStack projects, is written with the following design
+guidelines in mind:
+
+* **Component based architecture**: Quickly add new behaviors
+* **Highly available**: Scale to very serious workloads
+* **Fault tolerant**: Isolated processes avoid cascading failures
+* **Recoverable**: Failures should be easy to diagnose, debug, and rectify
+* **Open standards**: Be a reference implementation for a community-driven api
+
+This documentation is generated by the Sphinx toolkit and lives in the source
+tree.  Additional documentation on Glance and other components of OpenStack can
+be found on the `OpenStack wiki`_.  Also see the :doc:`community` page for
+other ways to interact with the community.
+
+.. _`OpenStack wiki`: http://wiki.openstack.org
+
+Concepts
 ========
 
-The Glance project provides services for discovering, registering, and
-retrieving virtual machine images. Glance has a RESTful API that allows
-querying of VM image metadata as well as retrieval of the actual image.
-
-.. toctree::
-    :maxdepth: 1
-
-The Glance API
+.. toctree::
+   :maxdepth: 1
+
+   identifiers
+   registries
+
+Using Glance
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   glanceapi
+   client
+
+Developer Docs
 ==============
 
-Glance has a RESTful API that exposes both metadata about registered virtual
-machine images and the image data itself.
-
-A host that runs the `bin/glance-api` service is said to be a *Glance API
-Server*.
-
-Assume there is a Glance API server running at the URL
-http://glance.openstack.org. 
-
-Let's walk through how a user might request information from this server.
-
-Requesting a List of Public VM Images
--------------------------------------
-
-We want to see a list of available virtual machine images that the Glance
-server knows about.
-
-We issue a `GET` request to http://glance.openstack.org/images/ to retrieve
-this list of available *public* images. The data is returned as a JSON-encoded
-mapping in the following format::
-
-  {'images': [
-    {'uri': 'http://glance.openstack.org/images/1',
-     'name': 'Ubuntu 10.04 Plain',
-     'type': 'kernel',
-     'size': '5368709120'}
-    ...]}
-
-Notes:
-
- * All images returned from the above `GET` request are *public* images
-
-
-Requesting Detailed Metadata on Public VM Images
-------------------------------------------------
-
-We want to see more detailed information on available virtual machine images
-that the Glance server knows about.
-
-We issue a `GET` request to http://glance.openstack.org/images/detail to
-retrieve this list of available *public* images. The data is returned as a
-JSON-encoded mapping in the following format::
-
-  {'images': [
-    {'uri': 'http://glance.openstack.org/images/1',
-     'name': 'Ubuntu 10.04 Plain 5GB',
-     'type': 'kernel',
-     'size': '5368709120',
-     'store': 'swift',
-     'created_at': '2010-02-03 09:34:01',
-     'updated_at': '2010-02-03 09:34:01',
-     'deleted_at': '',
-     'status': 'available',
-     'is_public': True,
-     'properties': {'distro': 'Ubuntu 10.04 LTS'}},
-    ...]}
-
-Notes:
-
- * All images returned from the above `GET` request are *public* images
- * All timestamps returned are in UTC
- * The `updated_at` timestamp is the timestamp when an image's metadata
-   was last updated, not it's image data, as all image data is immutable
-   once stored in Glance
- * The `properties` field is a mapping of free-form key/value pairs that
-   have been saved with the image metadata
-
-
-Requesting Detailed Metadata on a Specific Image
-------------------------------------------------
-
-We want to see detailed information for a specific virtual machine image
-that the Glance server knows about.
-
-We have queried the Glance server for a list of public images and the
-data returned includes the `uri` field for each available image. This
-`uri` field value contains the exact location needed to get the metadata
-for a specific image.
-
-Continuing the example from above, in order to get metadata about the
-first public image returned, we can issue a `HEAD` request to the Glance
-server for the image's URI.
-
-We issue a `HEAD` request to http://glance.openstack.org/images/1 to
-retrieve complete metadata for that image. The metadata is returned as a
-set of HTTP headers that begin with the prefix `x-image-meta-`. The
-following shows an example of the HTTP headers returned from the above
-`HEAD` request::
-
-  x-image-meta-uri              http://glance.openstack.org/images/1
-  x-image-meta-name             Ubuntu 10.04 Plain 5GB
-  x-image-meta-type             kernel
-  x-image-meta-size             5368709120
-  x-image-meta-store            swift
-  x-image-meta-created_at       2010-02-03 09:34:01
-  x-image-meta-updated_at       2010-02-03 09:34:01
-  x-image-meta-deleted_at       
-  x-image-meta-status           available
-  x-image-meta-is_public        True
-  x-image-meta-property-distro  Ubuntu 10.04 LTS
-
-Notes:
-
- * All timestamps returned are in UTC
- * The `x-image-meta-updated_at` timestamp is the timestamp when an
-   image's metadata was last updated, not it's image data, as all 
-   image data is immutable once stored in Glance
- * There may be multiple headers that begin with the prefix
-   `x-image-meta-property-`.  These headers are free-form key/value pairs
-   that have been saved with the image metadata. The key is the string
-   after `x-image-meta-property-` and the value is the value of the header
-
-
-Retrieving a Virtual Machine Image
-----------------------------------
-
-We want to retrieve that actual raw data for a specific virtual machine image
-that the Glance server knows about.
-
-We have queried the Glance server for a list of public images and the
-data returned includes the `uri` field for each available image. This
-`uri` field value contains the exact location needed to get the metadata
-for a specific image.
-
-Continuing the example from above, in order to get metadata about the
-first public image returned, we can issue a `HEAD` request to the Glance
-server for the image's URI.
-
-We issue a `GET` request to http://glance.openstack.org/images/1 to
-retrieve metadata for that image as well as the image itself encoded
-into the response body.
-
-The metadata is returned as a set of HTTP headers that begin with the
-prefix `x-image-meta-`. The following shows an example of the HTTP headers
-returned from the above `GET` request::
-
-  x-image-meta-uri              http://glance.openstack.org/images/1
-  x-image-meta-name             Ubuntu 10.04 Plain 5GB
-  x-image-meta-type             kernel
-  x-image-meta-size             5368709120
-  x-image-meta-store            swift
-  x-image-meta-created_at       2010-02-03 09:34:01
-  x-image-meta-updated_at       2010-02-03 09:34:01
-  x-image-meta-deleted_at       
-  x-image-meta-status           available
-  x-image-meta-is_public        True
-  x-image-meta-property-distro  Ubuntu 10.04 LTS
-
-Notes:
-
- * All timestamps returned are in UTC
- * The `x-image-meta-updated_at` timestamp is the timestamp when an
-   image's metadata was last updated, not it's image data, as all 
-   image data is immutable once stored in Glance
- * There may be multiple headers that begin with the prefix
-   `x-image-meta-property-`.  These headers are free-form key/value pairs
-   that have been saved with the image metadata. The key is the string
-   after `x-image-meta-property-` and the value is the value of the header
- * The response's `Content-Length` header shall be equal to the value of
-   the `x-image-meta-size` header
- * The image data itself will be the body of the HTTP response returned
-   from the request, which will have content-type of
-   `application/octet-stream`.
-
-
-.. toctree::
-    :maxdepth: 1
-
-
-Adding a New Virtual Machine Image
-----------------------------------
-
-We have created a new virtual machine image in some way (created a
-"golden image" or snapshotted/backed up an existing image) and we
-wish to do two things:
-
- * Store the disk image data in Glance
- * Store metadata about this image in Glance
-
-We can do the above two activities in a single call to the Glance API.
-Assuming, like in the examples above, that a Glance API server is running
-at `glance.openstack.org`, we issue a `POST` request to add an image to
-Glance::
-
-  POST http://glance.openstack.org/images/
-
-The metadata about the image is sent to Glance in HTTP headers. The body
-of the HTTP request to the Glance API will be the MIME-encoded disk
-image data.
-
-
-Adding Image Metadata in HTTP Headers
-*************************************
-
-Glance will view as image metadata any HTTP header that it receives in a
-`POST` request where the header key is prefixed with the strings
-`x-image-meta-` and `x-image-meta-property-`.
-
-The list of metadata headers that Glance accepts are listed below.
-
- * `x-image-meta-name`
-
-   This header is required. Its value should be the name of the image.
-
-   Note that the name of an image *is not unique to a Glance node*. It
-   would be an unrealistic expectation of users to know all the unique
-   names of all other user's images.
-
- * `x-image-meta-id`
-
-   This header is optional. 
-   
-   When present, Glance will use the supplied identifier for the image.
-   If the identifier already exists in that Glance node, then a
-   `409 Conflict` will be returned by Glance.
-
-   When this header is *not* present, Glance will generate an identifier
-   for the image and return this identifier in the response (see below)
-
- * `x-image-meta-store`
-
-   This header is optional. Valid values are one of `file` or `swift`
-
-   When present, Glance will attempt to store the disk image data in the
-   backing store indicated by the value of the header. If the Glance node
-   does not support the backing store, Glance will return a `400 Bad Request`.
-
-   When not present, Glance will store the disk image data in the backing
-   store that is marked default. See the configuration option `default_store`
-   for more information.
-
- * `x-image-meta-type`
-
-   This header is required. Valid values are one of `kernel`, `machine`, `raw`,
-   or `ramdisk`.
-
- * `x-image-meta-size`
-
-   This header is optional.
-
-   When present, Glance assumes that the expected size of the request body
-   will be the value of this header. If the length in bytes of the request
-   body *does not match* the value of this header, Glance will return a
-   `400 Bad Request`.
-
-   When not present, Glance will calculate the image's size based on the size
-   of the request body.
-
- * `x-image-meta-is_public`
-
-   This header is optional.
-
-   When present, Glance converts the value of the header to a boolean value,
-   so "on, 1, true" are all true values. When true, the image is marked as
-   a public image, meaning that any user may view its metadata and may read
-   the disk image from Glance.
-
-   When not present, the image is assumed to be *not public* and specific to
-   a user.
-
- * `x-image-meta-property-*`
-
-   When Glance receives any HTTP header whose key begins with the string prefix
-   `x-image-meta-property-`, Glance adds the key and value to a set of custom,
-   free-form image properties stored with the image.  The key is the
-   lower-cased string following the prefix `x-image-meta-property-` with dashes
-   and punctuation replaced with underscores.
-
-   For example, if the following HTTP header were sent::
-
-      x-image-meta-property-distro  Ubuntu 10.10
-
-   Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
-   image in Glance.
-
-   There is no limit on the number of free-form key/value attributes that can
-   be attached to the image.  However, keep in mind that the 8K limit on the
-   size of all HTTP headers sent in a request will effectively limit the number
-   of image properties.
-  
-
-.. toctree::
-    :maxdepth: 1
-
-Image Identifiers
-=================
-
-Images are uniquely identified by way of a URI that
-matches the following signature::
-
-  <Glance Server Location>/images/<ID>
-
-where `<Glance Server Location>` is the resource location of the Glance service
-that knows about an image, and `<ID>` is the image's identifier that is
-*unique to that Glance server*.
-
-.. toctree::
-    :maxdepth: 1
-
-Image Registration
-==================
-
-Image metadata made available through Glance can be stored in image
-*registries*. Image registries are any web service that adheres to the
-Glance RESTful API for image metadata.
-
-.. toctree::
-    :maxdepth: 1
-
-Using Glance Programmatically with Glance's Client
-==================================================
-
-While it is perfectly acceptable to issue HTTP requests directly to Glance
-via its RESTful API, sometimes it is better to be able to access and modify
-image resources via a client class that removes some of the complexity and
-tedium of dealing with raw HTTP requests.
-
-Glance includes a client class for just this purpose. You can retrieve
-metadata about an image, change metadata about an image, remove images, and
-of course retrieve an image itself via this client class.
-
-Below are some examples of using Glance's Client class.  We assume that
-there is a Glance server running at the address `glance.openstack.org`
-on port `9292`.
-
-Requesting a List of Public VM Images
--------------------------------------
-
-We want to see a list of available virtual machine images that the Glance
-server knows about.
-
-Using Glance's Client, we can do this using the following code::
-
-  from glance import client
-
-  c = client.Client("glance.openstack.org", 9292)
-
-  print c.get_images()
-
-
-Requesting Detailed Metadata on Public VM Images
-------------------------------------------------
-
-We want to see more detailed information on available virtual machine images
-that the Glance server knows about.
-
-Using Glance's Client, we can do this using the following code::
-
-  from glance import client
-
-  c = client.Client("glance.openstack.org", 9292)
-
-  print c.get_images_detailed()
-
-
-Requesting Detailed Metadata on a Specific Image
-------------------------------------------------
-
-We want to see detailed information for a specific virtual machine image
-that the Glance server knows about.
-
-We have queried the Glance server for a list of public images and the
-data returned includes the `uri` field for each available image. This
-`uri` field value contains the exact location needed to get the metadata
-for a specific image.
-
-Continuing the example from above, in order to get metadata about the
-first public image returned, we can use the following code::
-
-  from glance import client
-
-  c = client.Client("glance.openstack.org", 9292)
-
-  print c.get_image_meta("http://glance.openstack.org/images/1")
-
-
-Retrieving a Virtual Machine Image
-----------------------------------
-
-We want to retrieve that actual raw data for a specific virtual machine image
-that the Glance server knows about.
-
-We have queried the Glance server for a list of public images and the
-data returned includes the `uri` field for each available image. This
-`uri` field value contains the exact location needed to get the metadata
-for a specific image.
-
-Continuing the example from above, in order to get both the metadata about the
-first public image returned and its image data, we can use the following code::
-
-  from glance import client
-
-  c = client.Client("glance.openstack.org", 9292)
-
-  meta, image_file = c.get_image("http://glance.openstack.org/images/1")
-
-  print meta
-
-  f = open('some_local_file', 'wb')
-  for chunk in image_file:
-      f.write(chunk)
-  f.close()
-
-Note that the return from Client.get_image() is a tuple of (`metadata`, `file`)
-where `metadata` is a mapping of metadata about the image and `file` is a
-generator that yields chunks of image data.
-
-
-.. toctree::
-    :maxdepth: 1
-
-
-Adding a New Virtual Machine Image
-----------------------------------
-
-We have created a new virtual machine image in some way (created a
-"golden image" or snapshotted/backed up an existing image) and we
-wish to do two things:
-
- * Store the disk image data in Glance
- * Store metadata about this image in Glance
-
-We can do the above two activities in a single call to the Glance client.
-Assuming, like in the examples above, that a Glance API server is running
-at `glance.openstack.org`, we issue a call to `glance.client.Client.add_image`.
-
-The method signature is as follows::
-
-  glance.client.Client.add_image(image_meta, image_data=None)
-
-The `image_meta` argument is a mapping containing various image metadata. The
-`image_data` argument is the disk image data.
-
-The list of metadata that `image_meta` can contain are listed below.
-
- * `name`
-
-   This key/value is required. Its value should be the name of the image.
-
-   Note that the name of an image *is not unique to a Glance node*. It
-   would be an unrealistic expectation of users to know all the unique
-   names of all other user's images.
-
- * `id`
-
-   This key/value is optional. 
-   
-   When present, Glance will use the supplied identifier for the image.
-   If the identifier already exists in that Glance node, then a
-   `glance.common.exception.Duplicate` will be raised.
-
-   When this key/value is *not* present, Glance will generate an identifier
-   for the image and return this identifier in the response (see below)
-
- * `store`
-
-   This key/value is optional. Valid values are one of `file` or `swift`
-
-   When present, Glance will attempt to store the disk image data in the
-   backing store indicated by the value. If the Glance node does not support
-   the backing store, Glance will raise a `glance.common.exception.BadRequest`
-
-   When not present, Glance will store the disk image data in the backing
-   store that is marked default. See the configuration option `default_store`
-   for more information.
-
- * `type`
-
-   This key/values is required. Valid values are one of `kernel`, `machine`,
-   `raw`, or `ramdisk`.
-
- * `size`
-
-   This key/value is optional.
-
-   When present, Glance assumes that the expected size of the request body
-   will be the value. If the length in bytes of the request body *does not
-   match* the value, Glance will raise a `glance.common.exception.BadRequest`
-
-   When not present, Glance will calculate the image's size based on the size
-   of the request body.
-
- * `is_public`
-
-   This key/value is optional.
-
-   When present, Glance converts the value to a boolean value, so "on, 1, true"
-   are all true values. When true, the image is marked as a public image,
-   meaning that any user may view its metadata and may read the disk image from
-   Glance.
-
-   When not present, the image is assumed to be *not public* and specific to
-   a user.
-
- * `properties`
-
-   This key/value is optional.
-
-   When present, the value is assumed to be a mapping of free-form key/value
-   attributes to store with the image.
-
-   For example, if the following is the value of the `properties` key in the
-   `image_meta` argument::
-
-      {'distro': 'Ubuntu 10.10'}
-
-   Then a key/value pair of "distro"/"Ubuntu 10.10" will be stored with the
-   image in Glance.
-
-   There is no limit on the number of free-form key/value attributes that can
-   be attached to the image with `properties`.  However, keep in mind that there
-   is a 8K limit on the size of all HTTP headers sent in a request and this
-   number will effectively limit the number of image properties.
-
-As a complete example, the following code would add a new machine image to
-Glance::
-
-  from glance.client import Client
-
-  c = Client("glance.openstack.org", 9292)
-
-  meta = {'name': 'Ubuntu 10.10 5G',
-          'type': 'machine',
-          'is_public': True,
-          'properties': {'distro': 'Ubuntu 10.10'}}
-
-  new_meta = c.add_image(meta, open('/path/to/image.tar.gz'))
-
-  print 'Stored image. Got identifier: %s' % new_meta['id']
-
-
-.. toctree::
-    :maxdepth: 1
+.. toctree::
+   :maxdepth: 1
+
+   community
+
+Outstanding Documentation Tasks
+===============================
+
+.. todolist::
 
 Indices and tables
 ==================

=== added file 'doc/source/registries.rst'
--- doc/source/registries.rst	1970-01-01 00:00:00 +0000
+++ doc/source/registries.rst	2010-12-23 17:34:13 +0000
@@ -0,0 +1,22 @@
+..
+      Copyright 2010 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Image Registries
+================
+
+Image metadata made available through Glance can be stored in image
+*registries*. Image registries are any web service that adheres to the
+Glance RESTful API for image metadata.