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

[Jay Pipes]

Adds man pages for glance-registry and glance-api programs. Adds Getting Started guide to the Glance documentation.

Fixes Bug #704842

[Devin Carlen (devcamcar)]

lgtm

review: Approve

[Rick Harris (rconradharris)]

Great work Jay, thanks!

review: Approve

[Ed Leafe (ed-leafe)]

lgtm

review: Approve

[OpenStack Infra (hudson-openstack)]

The attempt to merge lp:~jaypipes/glance/bug704842 into lp:glance failed. Below is the output from the failed tests.

Traceback (most recent call last):
  File "setup.py", line 23, in <module>
    class local_BuildDoc(BuildDoc):
NameError: name 'BuildDoc' is not defined

=== modified file 'doc/source/conf.py'
--- doc/source/conf.py	2011-01-04 22:00:37 +0000
+++ doc/source/conf.py	2011-01-21 18:02:13 +0000
@@ -76,9 +76,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.2'
+release = '0.1.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -117,6 +117,18 @@
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['glance.']
 
+# -- Options for man page output -----------------------------------------------
+
+# Grouping the document tree for man pages. 
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+man_pages = [
+    ('man/glanceapi', 'glance-api', u'Glance API Server',
+     [u'OpenStack'], 1),
+    ('man/glanceregistry', 'glance-registry', u'Glance Registry Server',
+     [u'OpenStack'], 1)
+ ]
+
 
 # -- Options for HTML output -------------------------------------------------
 

=== added file 'doc/source/gettingstarted.rst'
--- doc/source/gettingstarted.rst	1970-01-01 00:00:00 +0000
+++ doc/source/gettingstarted.rst	2011-01-21 18:02:13 +0000
@@ -0,0 +1,123 @@
+..
+      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.
+
+Quick Guide to Getting Started with Glance
+==========================================
+
+Glance is a server that provides the following services:
+
+* Ability to store and retrieve virtual machine images
+* Ability to store and retrieve metadata about these virtual machine images
+* FUTURE: Convert a virtual machine image from one format to another
+* FUTURE: Help caching proxies such as Varnish or Squid cache machine images
+
+Communication with Glance occurs via a REST-like HTTP interface.
+
+However, Glance includes a :doc:`Client <client>` class that makes working with Glance
+easy and straightforward.
+
+In the Cactus release, there will be also command-line tools for
+interacting with Glance.
+
+Overview of Glance Architecture
+-------------------------------
+
+There are two main parts to Glance's architecture:
+
+* Glance API server
+* Glance Registry server(s)
+
+Glance API Server
+*****************
+
+The API server is the main interface for Glance. It routes requests from
+clients to registries of image metadata and to its **backend stores**, which
+are the mechanisms by which Glance actually saves incoming virtual machine
+images.
+
+The backend stores that Glance can work with are as follows:
+
+* **Swift**
+
+  Swift is the highly-available object storage project in OpenStack. More
+  information can be found about Swift `here <http://swift.openstack.org>`_.
+
+* **Filesystem**
+
+  The default backend that Glance uses to store virtual machine images
+  is the filesystem backend. This simple backend writes image files to the
+  local filesystem.
+
+* **S3**
+
+  This backend allows Glance to store virtual machine images in Amazon's
+  S3 service.
+
+* **HTTP**
+
+  Glance can read virtual machine images that are available via
+  HTTP somewhere on the Internet.  This store is **readonly**
+
+Glance Registry Servers
+***********************
+
+Glance registry servers are servers that conform to the Glance Registry API.
+Glance ships with a reference implementation of a registry server that
+complies with this API (``bin/glance-registry``).
+
+
+Starting Up Glance's Servers
+----------------------------
+
+To get started using Glance, you must first start the Glance API server. 
+After installing Glance, starting up the Glance API server is easy. Simply
+start the ``glance-api`` program, like so::
+
+  $> glance-api
+
+Configuring the Glance API server
+*********************************
+
+There are a few options that can be supplied to the API server when
+starting it up:
+
+* ``verbose``
+
+  Show more verbose/debugging output
+
+* ``api_host``
+
+  Address of the host the registry runs on. Defaults to 0.0.0.0.
+
+* ``api_port``
+
+  Port the registry server listens on. Defaults to 9292.
+
+* ``default_store``
+
+  The store that the Glance API server will use by default to store
+  images that are added to it. The default value is `filesystem`, and
+  possible choices are: `filesystem`, `swift`, and `s3`.
+
+* ``filesystem_store_datadir``
+
+  Directory where the filesystem store can write images to. This directory
+  must be writeable by the user that runs ``glance-api``
+
+.. todo::
+
+Link to docs on the different stores when the documentation on Glance
+stores is complete.

=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2011-01-17 18:09:14 +0000
+++ doc/source/index.rst	2011-01-21 18:02:13 +0000
@@ -57,6 +57,7 @@
 .. toctree::
    :maxdepth: 1
 
+   gettingstarted
    glanceapi
    client
 

=== added directory 'doc/source/man'
=== added file 'doc/source/man/glanceapi.rst'
--- doc/source/man/glanceapi.rst	1970-01-01 00:00:00 +0000
+++ doc/source/man/glanceapi.rst	2011-01-21 18:02:13 +0000
@@ -0,0 +1,63 @@
+==========
+glance-api
+==========
+
+---------------------------------------
+Server for the Glance Image Service API
+---------------------------------------
+
+:Author: [e-mail]
+:Date:   2010-11-16
+:Copyright: OpenStack LLC
+:Version: 0.1.2
+:Manual section: 1
+:Manual group: cloud computing
+
+SYNOPSIS
+========
+
+  glance-api [options]
+
+DESCRIPTION
+===========
+
+glance-api is a server daemon that serves the Glance API
+
+OPTIONS
+=======
+
+  **General options**
+
+  **-v, --verbose**
+        Print more verbose output
+
+  **--api_host=HOST**
+        Address of host running ``glance-api``. Defaults to `0.0.0.0`.
+
+  **--api_port=PORT**
+        Port that ``glance-api`` listens on. Defaults to `9292`.
+
+  **--default_store=STORE**
+        The default backend store that Glance should use when storing virtual
+        machine images. The default value is `filesystem`. Choices are any of
+        `filesystem`, `swift`, or `s3`
+
+  **--filesystem_store_datadir=DIR**
+        The directory that the `filesystem` backend store should use to write
+        virtual machine images. This directory should be writeable by the user
+        running ``glance-api``
+
+FILES
+========
+
+None
+
+SEE ALSO
+========
+
+* `OpenStack Glance <http://glance.openstack.org>`__
+
+BUGS
+====
+
+* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

=== added file 'doc/source/man/glanceregistry.rst'
--- doc/source/man/glanceregistry.rst	1970-01-01 00:00:00 +0000
+++ doc/source/man/glanceregistry.rst	2011-01-21 18:02:13 +0000
@@ -0,0 +1,58 @@
+===============
+glance-registry
+===============
+
+--------------------------------------
+Server for the Glance Registry Service
+--------------------------------------
+
+:Author: [e-mail]
+:Date:   2010-11-16
+:Copyright: OpenStack LLC
+:Version: 0.1.2
+:Manual section: 1
+:Manual group: cloud computing
+
+SYNOPSIS
+========
+
+  glance-registry [options]
+
+DESCRIPTION
+===========
+
+glance-registry is the reference implementation of a server daemon that serves
+image metadata based on the Glance Registry REST-like API.
+
+OPTIONS
+=======
+
+  **General options**
+
+  **-v, --verbose**
+        Print more verbose output
+
+  **--registry_host=HOST**
+        Address of host running ``glance-registry``. Defaults to `0.0.0.0`.
+
+  **--registry_port=PORT**
+        Port that ``glance-registry`` listens on. Defaults to `9191`.
+
+  **--sql_connection=CONN_STRING**
+        A proper SQLAlchemy connection string as described
+        `here <http://www.sqlalchemy.org/docs/05/reference/sqlalchemy/connections.html?highlight=engine#sqlalchemy.create_engine>`_
+
+FILES
+========
+
+None
+
+SEE ALSO
+========
+
+* `OpenStack Glance <http://glance.openstack.org>`__
+
+BUGS
+====
+
+* Glance is sourced in Launchpad so you can view current bugs at `OpenStack Glance <http://glance.openstack.org>`__

=== modified file 'doc/source/registries.rst'
--- doc/source/registries.rst	2011-01-18 21:01:49 +0000
+++ doc/source/registries.rst	2011-01-21 18:02:13 +0000
@@ -21,13 +21,13 @@
 `registries`. Image registries are any web service that adheres to the
 Glance REST-like API for image metadata.
 
-Glance comes with a server program ``bin/glance-registry`` that acts
+Glance comes with a server program ``glance-registry`` that acts
 as a reference implementation of a Glance Registry.
 
-Using ``bin/glance-registry``
------------------------------
+Using ``glance-registry``, the Glance Registry reference implementation
+-----------------------------------------------------------------------
 
-As mentioned above, ``bin/glance-registry`` is the reference registry
+As mentioned above, ``glance-registry`` is the reference registry
 server implementation that ships with Glance. It uses a SQL database
 to store information about an image, and publishes this information
 via an HTTP/REST-like interface.
@@ -38,7 +38,7 @@
 Starting the Glance registry server is trivial. Simply call the program
 from the command line, as the following example shows::
 
-  jpipes@serialcoder:~/repos/glance/trunk$ ./bin/glance-registry
+  $> glance-registry
   (5588) wsgi starting up on http://0.0.0.0:9191/
 
 Configuring the server

=== modified file 'setup.py'
--- setup.py	2011-01-18 17:31:40 +0000
+++ setup.py	2011-01-21 18:02:13 +0000
@@ -14,10 +14,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import os
+import subprocess
+
 from setuptools import setup, find_packages
 from setuptools.command.sdist import sdist
-import os
-import subprocess
+from sphinx.setup_command import BuildDoc
+
+
+class local_BuildDoc(BuildDoc):
+    def run(self):
+        for builder in ['html', 'man']:
+            self.builder = builder
+            self.finalize_options()
+            BuildDoc.run(self)
 
 
 class local_sdist(sdist):
@@ -38,6 +48,9 @@
 name = 'glance'
 version = '0.1.3pre'
 
+cmdclass = {'sdist': local_sdist,
+            'build_sphinx': local_BuildDoc}
+
 setup(
     name=name,
     version=version,
@@ -48,7 +61,7 @@
     url='https://launchpad.net/glance',
     packages=find_packages(exclude=['tests', 'bin']),
     test_suite='nose.collector',
-    cmdclass={'sdist': local_sdist},
+    cmdclass=cmdclass,
     classifiers=[
         'Development Status :: 4 - Beta',
         'License :: OSI Approved :: Apache Software License',