Merge to remote.

7 files changed, 252 insertions, 3 deletions

diff --git a/doc/ext/__init__.py b/doc/ext/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/ext/__init__.py
diff --git a/doc/ext/nova_todo.py b/doc/ext/nova_todo.py
new file mode 100644
index 000000000..7a06b1bf9
--- /dev/null
+++ b/doc/ext/nova_todo.py
@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+# This is a hack of the builtin todo extension, to make the todo_list more user friendly
+
+from sphinx.ext.todo import *
+from docutils.parsers.rst import directives
+
+def _(s):
+    return s
+
+def process_todo_nodes(app, doctree, fromdocname):
+    if not app.config['todo_include_todos']:
+        for node in doctree.traverse(todo_node):
+            node.parent.remove(node)
+
+    # Replace all todolist nodes with a list of the collected todos.
+    # Augment each todo with a backlink to the original location.
+    env = app.builder.env
+
+    if not hasattr(env, 'todo_all_todos'):
+        env.todo_all_todos = []
+
+    my_todo_list = nodes.bullet_list("", nodes.Text('',''));
+
+    # remove the item that was added in the constructor, since I'm tired of 
+    # reading through docutils for the proper way to construct an empty list
+    my_todo_list.remove(my_todo_list[0]) 
+
+    my_todo_list.set_class('todo_list')
+    for node in doctree.traverse(todolist):
+        if not app.config['todo_include_todos']:
+            node.replace_self([])
+            continue
+
+        content = []
+
+        for todo_info in env.todo_all_todos:
+            para = nodes.paragraph()
+            filename = env.doc2path(todo_info['docname'], base=None)
+
+            # Create a reference
+            newnode = nodes.reference('', '')
+
+            link = _('%s, line %d') % (filename, todo_info['lineno']);
+            innernode = nodes.emphasis(link, link)
+            newnode['refdocname'] = todo_info['docname']
+
+            try:
+                newnode['refuri'] = app.builder.get_relative_uri(
+                    fromdocname, todo_info['docname'])
+                newnode['refuri'] += '#' + todo_info['target']['refid']
+            except NoUri:
+                # ignore if no URI can be determined, e.g. for LaTeX output
+                pass
+
+            newnode.append(innernode)
+            para += newnode
+            para.set_class("link")
+
+            todo_entry = todo_info['todo']
+                
+            env.resolve_references(todo_entry, todo_info['docname'], app.builder)
+
+            item = nodes.list_item("", para)
+            todo_entry[1].set_class("details")
+            item.append(todo_entry[1])
+
+            my_todo_list.insert(0, item)
+
+
+        node.replace_self(my_todo_list)
+
+def setup(app):
+    app.add_config_value('todo_include_todos', False, False)
+
+    app.add_node(todolist)
+    app.add_node(todo_node,
+                 html=(visit_todo_node, depart_todo_node),
+                 latex=(visit_todo_node, depart_todo_node),
+                 text=(visit_todo_node, depart_todo_node))
+
+    app.add_directive('todo', Todo)
+    app.add_directive('todolist', TodoList)
+    app.connect('doctree-read', process_todos)
+    app.connect('doctree-resolved', process_todo_nodes)
+    app.connect('env-purge-doc', purge_todos)
+
diff --git a/doc/source/_static/tweaks.css b/doc/source/_static/tweaks.css
new file mode 100644
index 000000000..d1cbed96d
--- /dev/null
+++ b/doc/source/_static/tweaks.css
@@ -0,0 +1,44 @@
+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 #FF6666;
+}
+
+div.admonition p.admonition-title {
+    background-color: #FF6666;
+    border-bottom: 1px solid #FF6666;
+}
+
+em {
+    font-style: normal;
+}
+
+table.docutils {
+	font-size: 11px;
+}
\ No newline at end of file
diff --git a/doc/source/_theme/layout.html b/doc/source/_theme/layout.html
new file mode 100644
index 000000000..ed1cab0a6
--- /dev/null
+++ b/doc/source/_theme/layout.html
@@ -0,0 +1,2 @@
+{% extends "sphinxdoc/layout.html" %}
+{% set css_files = css_files + ['_static/tweaks.css'] %}
diff --git a/doc/source/_theme/theme.conf b/doc/source/_theme/theme.conf
new file mode 100644
index 000000000..e039fe01f
--- /dev/null
+++ b/doc/source/_theme/theme.conf
@@ -0,0 +1,5 @@
+[theme]
+inherit = sphinxdoc
+stylesheet = sphinxdoc.css
+pygments_style = friendly
+
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 3f6ca2313..177c6568e 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -17,13 +17,14 @@ import sys, os
 # 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.insert(0, os.path.abspath('../../'))
-
+sys.path.insert(0, '../')
+sys.path.insert(0, './')
 
 # -- 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', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'ext.nova_todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig']
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.
@@ -99,7 +100,8 @@ modindex_common_prefix = ['nova.']
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'sphinxdoc'
+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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 58c3cad58..7795ab75d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -27,6 +27,7 @@ Nova is written with the following design guidelines in mind:
 * **Fault-Tollerant**: Isloated 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
+* **API Compatibility**: Nova strives to provide API-compatible with popular systems like Amazon EC2
 
 This documentation is generated by the Sphinx toolkit and lives in the source
 tree.  Additional documentation on Nova and other components of OpenStack can
@@ -47,6 +48,115 @@ Contents
    devguide/index
    reaching.out
 
+Recommended System Configuration
+================================
+
+Although Nova can be run on a variety of system architectures, for most users the following will be simplest:
+
+* Ubuntu Lucid
+* 10GB Hard Disk Space
+* 512MB RAM
+
+For development, Nova can run from within a VM.
+
+Quickstart
+==========
+
+To make getting started with Nova easier, we provide a setup script that makes it easy to download and run the most recent version of Nova on your local machine.
+
+* sudo -i # become root
+* cd # go to home directory
+* git clone git://github.com/vishvananda/novascript.git
+* cd novascript
+
+Inside this directory, you will find nova.sh, which is a utility designed to assist with getting your development environment up and running.
+
+Use nova.sh to install and run the current trunk. You can also specify a specific branch by putting lp:~someone/nova/some-branch after the branch command
+
+* ./nova.sh branch
+* ./nova.sh install
+* ./nova.sh run
+
+The run command will drop you into a screen session with all of the workers running in different windows  You can use eucatools to run commands against the cloud.
+
+* euca-add-keypair test > test.pem
+* euca-run-instances -k test -t m1.tiny ami-tiny
+* euca-describe-instances
+
+To see output from the various workers, switch screen windows
+
+* <ctrl-a> "
+
+will give you a list of running windows.
+
+When the instance is running, you should be able to ssh to it.
+
+* chmod 600 test.pem
+* ssh -i test.pem root@10.0.0.3
+
+When you exit screen
+
+* <ctrl-a> <ctrl-d>
+
+nova will terminate.  It may take a while for nova to finish cleaning up.  If you exit the process before it is done because there were some problems in your build, you may have to clean up the nova processes manually.  If you had any instances running, you can attempt to kill them through the api:
+
+* ./nova.sh terminate
+
+Then you can destroy the screen:
+
+* ./nova.sh clean
+
+If things get particularly messed up, you might need to do some more intense cleanup.  Be careful, the following command will manually destroy all runnning virsh instances and attempt to delete all vlans and bridges.
+
+* ./nova.sh scrub
+
+You can edit files in the install directory or do a bzr pull to pick up new versions. You only need to do
+
+* ./nova.sh run
+
+to run nova after the first install.  The database should be cleaned up on each run.
+
+Notes
+-----
+
+The script starts nova-volume in fake mode, so it will not create any actual volumes.
+
+if you want to USE_VENV because you have different versions of python packages on your system that you want to keep, you should run install before branch:
+
+* ./nova.sh install
+* ./nova.sh branch
+* ./nova.sh run
+
+A sample image should be downloaded by the script, but if necessary you can download it by hand:
+
+* wget http://c2477062.cdn.cloudfiles.rackspacecloud.com/images.tgz
+
+untar the file to create a usable images directory
+
+* tar -zxf /path/to/images.tgz
+
+If you want to be able to contact the metadata server and route to the outside world from instances, you will need to make sure $HOST_IP is set properly.  The script attemps to grab it from ifconfig, but if you have multiple adapters set up, it may fail.  Fix it with export HOST_IP="<your public ip>":
+
+Customization
+-------------
+
+You can make nova use mysql instead of sqlite with USE_MYSQL, it will attempt to install mysql with the specified root password and create a database called nova.
+
+If you are running nova on bare metal that supports hardware virtualization, you should probably edit the libvirt line near the top
+
+* LIBVIRT_TYPE=kvm
+
+If you are running in a virtual machine and software emulation is too slow for you, you can use user mode linux.
+
+* LIBVIRT_TYPE=uml
+
+You will need a few bleeding edge packages to make it work, so you should make sure to use the PPA.
+
+* USE_PPA=1
+
+If you have any issues, there is usually someone in #openstack on irc.freenode.net that can help you out.
+
+
 
 Outstanding Documentation Tasks
 ===============================