Move docs to doc.

To better facilitate the building and publishing of sphinx
documentation by Jenkins we are moving all openstack projects with
sphinx documentation to a common doc tree structure. Documentation
goes in project/doc and build results go in project/doc/build.

Change-Id: I3ae14ac735d9b4c0b534eac9a9c142f8ccaac1b9

12 files changed, 758 insertions, 0 deletions

diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100644
index 0000000..1e184bb
--- /dev/null
+++ b/doc/source/api.rst
@@ -0,0 +1,67 @@
+The :mod:`cinderclient` Python API
+==================================
+
+.. module:: cinderclient
+   :synopsis: A client for the OpenStack Nova API.
+
+.. currentmodule:: cinderclient
+
+Usage
+-----
+
+First create an instance of :class:`OpenStack` with your credentials::
+
+    >>> from cinderclient import OpenStack
+    >>> cinder = OpenStack(USERNAME, PASSWORD, AUTH_URL)
+
+Then call methods on the :class:`OpenStack` object:
+
+.. class:: OpenStack
+
+    .. attribute:: backup_schedules
+
+        A :class:`BackupScheduleManager` -- manage automatic backup images.
+
+    .. attribute:: flavors
+
+        A :class:`FlavorManager` -- query available "flavors" (hardware
+        configurations).
+
+    .. attribute:: images
+
+        An :class:`ImageManager` -- query and create server disk images.
+
+    .. attribute:: ipgroups
+
+        A :class:`IPGroupManager` -- manage shared public IP addresses.
+
+    .. attribute:: servers
+
+        A :class:`ServerManager` -- start, stop, and manage virtual machines.
+
+    .. automethod:: authenticate
+
+For example::
+
+    >>> cinder.servers.list()
+    [<Server: buildslave-ubuntu-9.10>]
+
+    >>> cinder.flavors.list()
+    [<Flavor: 256 server>,
+     <Flavor: 512 server>,
+     <Flavor: 1GB server>,
+     <Flavor: 2GB server>,
+     <Flavor: 4GB server>,
+     <Flavor: 8GB server>,
+     <Flavor: 15.5GB server>]
+
+    >>> fl = cinder.flavors.find(ram=512)
+    >>> cinder.servers.create("my-server", flavor=fl)
+    <Server: my-server>
+
+For more information, see the reference:
+
+.. toctree::
+   :maxdepth: 2
+
+   ref/index
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 0000000..ccbe64b
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+#
+# python-cinderclient documentation build configuration file, created by
+# sphinx-quickstart on Sun Dec  6 14:19:25 2009.
+#
+# This file is execfile()d with current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# 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('.'))
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
+sys.path.insert(0, ROOT)
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'python-cinderclient'
+copyright = u'Rackspace, based on work by Jacob Kaplan-Moss'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2.6'
+# The full version, including alpha/beta/rc tags.
+release = '2.6.10'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- 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 = 'nature'
+
+# 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
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'python-cinderclientdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'python-cinderclient.tex', u'python-cinderclient Documentation',
+   u'Rackspace - based on work by Jacob Kaplan-Moss', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 0000000..d992f7c
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,45 @@
+Python bindings to the OpenStack Nova API
+==================================================
+
+This is a client for OpenStack Nova API. There's :doc:`a Python API
+<api>` (the :mod:`cinderclient` module), and a :doc:`command-line script
+<shell>` (installed as :program:`cinder`). Each implements the entire
+OpenStack Nova API.
+
+You'll need an `OpenStack Nova` account, which you can get by using `cinder-manage`.
+
+.. seealso::
+
+    You may want to read `Rackspace's API guide`__ (PDF) -- the first bit, at
+    least -- to get an idea of the concepts. Rackspace is doing the cloud
+    hosting thing a bit differently from Amazon, and if you get the concepts
+    this library should make more sense.
+
+    __ http://docs.rackspacecloud.com/servers/api/cs-devguide-latest.pdf
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   shell
+   api
+   ref/index
+   releases
+
+Contributing
+============
+
+Development takes place `on GitHub`__; please file bugs/pull requests there.
+
+__ https://github.com/rackspace/python-cinderclient
+
+Run tests with ``python setup.py test``.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/doc/source/ref/backup_schedules.rst b/doc/source/ref/backup_schedules.rst
new file mode 100644
index 0000000..cbd69e3
--- /dev/null
+++ b/doc/source/ref/backup_schedules.rst
@@ -0,0 +1,60 @@
+Backup schedules
+================
+
+.. currentmodule:: cinderclient
+
+Rackspace allows scheduling of weekly and/or daily backups for virtual
+servers. You can access these backup schedules either off the API object as
+:attr:`OpenStack.backup_schedules`, or directly off a particular
+:class:`Server` instance as :attr:`Server.backup_schedule`.
+
+Classes
+-------
+
+.. autoclass:: BackupScheduleManager
+   :members: create, delete, update, get
+   
+.. autoclass:: BackupSchedule
+   :members: update, delete
+   
+   .. attribute:: enabled
+   
+        Is this backup enabled? (boolean)
+        
+   .. attribute:: weekly
+   
+        The day of week upon which to perform a weekly backup.
+   
+   .. attribute:: daily
+   
+        The daily time period during which to perform a daily backup.
+        
+Constants
+---------
+
+Constants for selecting weekly backup days:
+
+    .. data:: BACKUP_WEEKLY_DISABLED
+    .. data:: BACKUP_WEEKLY_SUNDAY
+    .. data:: BACKUP_WEEKLY_MONDAY  
+    .. data:: BACKUP_WEEKLY_TUESDAY 
+    .. data:: BACKUP_WEEKLY_WEDNESDA
+    .. data:: BACKUP_WEEKLY_THURSDAY
+    .. data:: BACKUP_WEEKLY_FRIDAY  
+    .. data:: BACKUP_WEEKLY_SATURDAY
+    
+Constants for selecting hourly backup windows:
+
+    .. data:: BACKUP_DAILY_DISABLED   
+    .. data:: BACKUP_DAILY_H_0000_0200
+    .. data:: BACKUP_DAILY_H_0200_0400
+    .. data:: BACKUP_DAILY_H_0400_0600
+    .. data:: BACKUP_DAILY_H_0600_0800
+    .. data:: BACKUP_DAILY_H_0800_1000
+    .. data:: BACKUP_DAILY_H_1000_1200
+    .. data:: BACKUP_DAILY_H_1200_1400
+    .. data:: BACKUP_DAILY_H_1400_1600
+    .. data:: BACKUP_DAILY_H_1600_1800
+    .. data:: BACKUP_DAILY_H_1800_2000
+    .. data:: BACKUP_DAILY_H_2000_2200
+    .. data:: BACKUP_DAILY_H_2200_0000
diff --git a/doc/source/ref/exceptions.rst b/doc/source/ref/exceptions.rst
new file mode 100644
index 0000000..23618e3
--- /dev/null
+++ b/doc/source/ref/exceptions.rst
@@ -0,0 +1,14 @@
+Exceptions
+==========
+
+.. currentmodule:: cinderclient
+
+Exceptions
+----------
+
+Exceptions that the API might throw:
+
+.. automodule:: cinderclient
+   :members: OpenStackException, BadRequest, Unauthorized, Forbidden, 
+             NotFound, OverLimit
+
diff --git a/doc/source/ref/flavors.rst b/doc/source/ref/flavors.rst
new file mode 100644
index 0000000..12b396a
--- /dev/null
+++ b/doc/source/ref/flavors.rst
@@ -0,0 +1,35 @@
+Flavors
+=======
+
+From Rackspace's API documentation:
+
+    A flavor is an available hardware configuration for a server. Each flavor
+    has a unique combination of disk space, memory capacity and priority for
+    CPU time.
+    
+Classes
+-------
+
+.. currentmodule:: cinderclient
+
+.. autoclass:: FlavorManager
+   :members: get, list, find, findall
+
+.. autoclass:: Flavor
+   :members:
+   
+   .. attribute:: id
+   
+       This flavor's ID.
+       
+   .. attribute:: name
+   
+       A human-readable name for this flavor.
+   
+   .. attribute:: ram
+   
+       The amount of RAM this flavor has, in MB.
+       
+   .. attribute:: disk
+   
+       The amount of disk space this flavor has, in MB
diff --git a/doc/source/ref/images.rst b/doc/source/ref/images.rst
new file mode 100644
index 0000000..6ba6c24
--- /dev/null
+++ b/doc/source/ref/images.rst
@@ -0,0 +1,54 @@
+Images
+======
+
+.. currentmodule:: cinderclient
+
+An "image" is a snapshot from which you can create new server instances.
+
+From Rackspace's own API documentation:
+
+    An image is a collection of files used to create or rebuild a server.
+    Rackspace provides a number of pre-built OS images by default. You may
+    also create custom images from cloud servers you have launched. These
+    custom images are useful for backup purposes or for producing "gold"
+    server images if you plan to deploy a particular server configuration
+    frequently.
+
+Classes
+-------
+
+.. autoclass:: ImageManager
+   :members: get, list, find, findall, create, delete
+
+.. autoclass:: Image
+   :members: delete
+      
+   .. attribute:: id
+   
+       This image's ID.
+       
+   .. attribute:: name
+   
+       This image's name.
+       
+   .. attribute:: created
+   
+       The date/time this image was created.
+       
+   .. attribute:: updated
+   
+       The date/time this instance was updated.
+       
+   .. attribute:: status
+   
+       The status of this image (usually ``"SAVING"`` or ``ACTIVE``).
+       
+   .. attribute:: progress
+   
+       During saving of an image this'll be set to something between
+       0 and 100, representing a rough percentage done.
+       
+   .. attribute:: serverId
+   
+       If this image was created from a :class:`Server` then this attribute
+       will be set to the ID of the server whence this image came.
diff --git a/doc/source/ref/index.rst b/doc/source/ref/index.rst
new file mode 100644
index 0000000..c1fe136
--- /dev/null
+++ b/doc/source/ref/index.rst
@@ -0,0 +1,12 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+   
+   backup_schedules
+   exceptions
+   flavors
+   images
+   ipgroups
+   servers
\ No newline at end of file
diff --git a/doc/source/ref/ipgroups.rst b/doc/source/ref/ipgroups.rst
new file mode 100644
index 0000000..4c29f2e
--- /dev/null
+++ b/doc/source/ref/ipgroups.rst
@@ -0,0 +1,46 @@
+Shared IP addresses
+===================
+
+From the Rackspace API guide:
+
+    Public IP addresses can be shared across multiple servers for use in
+    various high availability scenarios. When an IP address is shared to
+    another server, the cloud network restrictions are modified to allow each
+    server to listen to and respond on that IP address (you may optionally
+    specify that the target server network configuration be modified). Shared
+    IP addresses can be used with many standard heartbeat facilities (e.g.
+    ``keepalived``) that monitor for failure and manage IP failover.
+
+    A shared IP group is a collection of servers that can share IPs with other
+    members of the group. Any server in a group can share one or more public
+    IPs with any other server in the group. With the exception of the first
+    server in a shared IP group, servers must be launched into shared IP
+    groups. A server may only be a member of one shared IP group.
+
+.. seealso::
+
+    Use :meth:`Server.share_ip` and `Server.unshare_ip` to share and unshare
+    IPs in a group.
+
+Classes
+-------
+
+.. currentmodule:: cinderclient
+
+.. autoclass:: IPGroupManager
+   :members: get, list, find, findall, create, delete
+   
+.. autoclass:: IPGroup
+   :members: delete
+   
+   .. attribute:: id
+   
+        Shared group ID.
+   
+   .. attribute:: name
+   
+        Name of the group.
+   
+   .. attribute:: servers
+   
+        A list of server IDs in this group.
diff --git a/doc/source/ref/servers.rst b/doc/source/ref/servers.rst
new file mode 100644
index 0000000..b02fca5
--- /dev/null
+++ b/doc/source/ref/servers.rst
@@ -0,0 +1,73 @@
+Servers
+=======
+
+A virtual machine instance.
+
+Classes
+-------
+
+.. currentmodule:: cinderclient
+
+.. autoclass:: ServerManager
+   :members: get, list, find, findall, create, update, delete, share_ip,
+             unshare_ip, reboot, rebuild, resize, confirm_resize,
+             revert_resize
+
+.. autoclass:: Server
+   :members: update, delete, share_ip, unshare_ip, reboot, rebuild, resize,
+             confirm_resize, revert_resize
+
+   .. attribute:: id
+
+        This server's ID.
+
+   .. attribute:: name
+
+        The name you gave the server when you booted it.
+
+   .. attribute:: imageId
+
+        The :class:`Image` this server was booted with.
+
+   .. attribute:: flavorId
+
+        This server's current :class:`Flavor`.
+
+   .. attribute:: hostId
+
+        Rackspace doesn't document this value. It appears to be SHA1 hash.
+
+   .. attribute:: status
+
+        The server's status (``BOOTING``, ``ACTIVE``, etc).
+
+   .. attribute:: progress
+
+        When booting, resizing, updating, etc., this will be set to a
+        value between 0 and 100 giving a rough estimate of the progress
+        of the current operation.
+
+   .. attribute:: addresses
+
+        The public and private IP addresses of this server. This'll be a dict
+        of the form::
+
+            {
+              "public" : ["67.23.10.138"],
+              "private" : ["10.176.42.19"]
+            }
+
+        You *can* get more than one public/private IP provisioned, but not
+        directly from the API; you'll need to open a support ticket.
+
+   .. attribute:: metadata
+
+        The metadata dict you gave when creating the server.
+
+Constants
+---------
+
+Reboot types:
+
+.. data:: REBOOT_SOFT
+.. data:: REBOOT_HARD
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
new file mode 100644
index 0000000..783b1ca
--- /dev/null
+++ b/doc/source/releases.rst
@@ -0,0 +1,99 @@
+=============
+Release notes
+=============
+
+2.5.8 (July 11, 2011)
+=====================
+* returns all public/private ips, not just first one
+* better 'cinder list' search options
+
+2.5.7 - 2.5.6 = minor tweaks
+
+2.5.5 (June 21, 2011)
+=====================
+* zone-boot min/max instance count added thanks to comstud
+* create for user added thanks to cerberus
+* fixed tests
+
+2.5.3 (June 15, 2011)
+=====================
+* ProjectID can be None for backwards compatability.
+* README/docs updated for projectId thanks to usrleon
+
+2.5.1 (June 10, 2011)
+=====================
+* ProjectID now part of authentication
+
+2.5.0 (June 3, 2011)
+=================
+
+* better logging thanks to GridDynamics
+
+2.4.4 (June 1, 2011)
+=================
+
+* added support for GET /servers with reservation_id (and /servers/detail)
+
+2.4.3 (May 27, 2011)
+=================
+
+* added support for POST /zones/select (client only, not cmdline)
+
+2.4 (March 7, 2011)
+=================
+
+* added Jacob Kaplan-Moss copyright notices to older/untouched files.
+
+
+2.3 (March 2, 2011)
+=================
+
+* package renamed to python-cinderclient. Module to cinderclient
+
+
+2.2 (March 1, 2011)
+=================
+
+* removed some license/copywrite notices from source that wasn't
+  significantly changed.
+
+
+2.1 (Feb 28, 2011)
+=================
+
+* shell renamed to cinder from cindertools
+
+* license changed from BSD to Apache
+
+2.0 (Feb 7, 2011)
+=================
+
+* Forked from https://github.com/jacobian/python-cloudservers
+
+* Rebranded to python-cindertools
+
+* Auth URL support
+
+* New OpenStack specific commands added (pause, suspend, etc)
+
+1.2 (August 15, 2010)
+=====================
+
+* Support for Python 2.4 - 2.7.
+
+* Improved output of :program:`cloudservers ipgroup-list`.
+
+* Made ``cloudservers boot --ipgroup <name>`` work (as well as ``--ipgroup
+  <id>``).
+
+1.1 (May 6, 2010)
+=================
+
+* Added a ``--files`` option to :program:`cloudservers boot` supporting
+  the upload of (up to five) files at boot time.
+
+* Added a ``--key`` option to :program:`cloudservers boot` to key the server
+  with an SSH public key at boot time. This is just a shortcut for ``--files``,
+  but it's a useful shortcut.
+
+* Changed the default server image to Ubuntu 10.04 LTS.
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
new file mode 100644
index 0000000..cff5cc7
--- /dev/null
+++ b/doc/source/shell.rst
@@ -0,0 +1,52 @@
+The :program:`cinder` shell utility
+=========================================
+
+.. program:: cinder
+.. highlight:: bash
+
+The :program:`cinder` shell utility interacts with OpenStack Nova API
+from the command line. It supports the entirety of the OpenStack Nova API.
+
+First, you'll need an OpenStack Nova account and an API key. You get this
+by using the `cinder-manage` command in OpenStack Nova.
+
+You'll need to provide :program:`cinder` with your OpenStack username and
+API key. You can do this with the :option:`--os_username`, :option:`--os_password`
+and :option:`--os_tenant_id` options, but it's easier to just set them as
+environment variables by setting two environment variables:
+
+.. envvar:: OS_USERNAME
+
+    Your OpenStack Nova username.
+
+.. envvar:: OS_PASSWORD
+
+    Your password.
+
+.. envvar:: OS_TENANT_NAME
+
+    Project for work.
+
+.. envvar:: OS_AUTH_URL
+
+    The OpenStack API server URL.
+
+.. envvar:: OS_COMPUTE_API_VERSION
+
+    The OpenStack API version.
+
+For example, in Bash you'd use::
+
+    export OS_USERNAME=yourname
+    export OS_PASSWORD=yadayadayada
+    export OS_TENANT_NAME=myproject
+    export OS_AUTH_URL=http://...
+    export OS_COMPUTE_API_VERSION=1.1
+    
+From there, all shell commands take the form::
+    
+    cinder <command> [arguments...]
+
+Run :program:`cinder help` to get a full list of all possible commands,
+and run :program:`cinder help <command>` to get detailed help for that
+command.