Merge pull request zerovm#39 from mgeisler/expand-doc

Expand documentation

doc/commands.rst

@@ -5,29 +5,42 @@ ZPM Commands
 The ``zpm`` script has the following top-level commands:
 
 
+.. _zpm-new:
+
 ``zpm new``
 -----------
 
+.. autocommand:: zpmlib.commands.new
+
 .. argparse::
    :module: zpmlib.commands
    :func: set_up_arg_parser
    :prog: zpm
    :path: new
 
 
+.. _zpm-deploy:
+
+
 ``zpm deploy``
 --------------
 
+.. autocommand:: zpmlib.commands.deploy
+
 .. argparse::
    :module: zpmlib.commands
    :func: set_up_arg_parser
    :prog: zpm
    :path: deploy
 
 
+.. _zpm-bundle:
+
 ``zpm bundle``
 --------------
 
+.. autocommand:: zpmlib.commands.bundle
+
 .. argparse::
    :module: zpmlib.commands
    :func: set_up_arg_parser

doc/conf.py

@@ -14,6 +14,7 @@
 
 import sys
 import os
+from sphinx.ext import autodoc
 
 # 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
@@ -23,7 +24,19 @@
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.1'
+
+
+class CommandDocumenter(autodoc.FunctionDocumenter):
+    objtype = 'command'
+    content_indent = ''
+
+    def add_directive_header(self, sig):
+        pass
+
+
+def setup(app):
+    app.add_autodocumenter(CommandDocumenter)
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

doc/index.rst

@@ -3,14 +3,15 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ZeroVM Package Manager's documentation!
-==================================================
+ZPM: ZeroVM Package Manager
+===========================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   intro
    commands
 
 

doc/intro.rst

@@ -0,0 +1,136 @@
+
+Introduction
+============
+
+The ZeroVM Package Manager, ZPM, is the tool you use to create and
+deploy ZeroVM applications.
+
+
+Creating a ZeroVM Application
+-----------------------------
+
+We will use a simple Python application as our running example.
+
+.. note::
+
+   As of version 0.1, ZPM only supports Python applications with no
+   third-party dependencies.
+
+To get started, we will show how to package a very simple "Hello
+World" application. There will be just one file, ``hello.py``, with
+the expected content::
+
+   print "Hello from ZeroVM!"
+
+To bundle this into a ZAR, ZPM needs a configuration file called
+``zar.json``.
+
+Configuration File
+""""""""""""""""""
+
+The ``zar.json`` file will look like this:
+
+.. code-block:: json
+
+   {
+       "execution": {
+           "groups" : [
+               {
+                   "name": "hello",
+                   "path": "file://python2.7:python",
+                   "args": "hello.py",
+                   "devices": [
+                       {"name": "python2.7"},
+                       {"name": "stdout"}
+                   ]
+               }
+           ]
+       },
+       "meta" : {
+           "name": "hello",
+           "Summary": "The hello app",
+           "Author-email": "Martin Geisler <[email protected]>",
+           "Version": "0.1"
+       },
+       "help" : {
+           "description": "A small \"Hello World\" app."
+       },
+       "bundling": [
+           "hello.py"
+       ]
+   }
+
+The file is in `JSON format <json_>`_ and describes the program to
+execute, some meta data about it, help about the program and its
+arguments (this program has none), and finally information about which
+files to include when bundling. We will get into more detail later
+about the different sections of the file.
+
+
+Bundling
+""""""""
+
+Simply running ``zpm bundle`` will create the ``hello.zar``::
+
+   $ zpm bundle
+   adding /home/mg/src/hello/hello.py
+   adding /home/mg/src/hello/zar.json
+   created hello.zar
+
+You see the files added to the ZAR --- here it's simply ``hello.py``
+together with the ``zar.json`` file containing the meta data.
+
+You can now publish ``hello.zar`` on your webserver, send it to your
+friends, etc. They will be able to run it after they deploy it like we
+describe next.
+
+Deployment
+""""""""""
+
+To deploy ``hello.zar``, you need access to a Zwift cluster (Swift
+running the ZeroVM middleware). Like the ``swift`` command line client
+for Swift, ``zpm`` will read your credentials from environemnt
+variables if you don't pass them on the command line. The environment
+variables are:
+
+.. code-block:: sh
+
+   export OS_TENANT_NAME=demo
+   export OS_USERNAME=demo
+   export OS_PASSWORD=pw
+   export OS_AUTH_URL=http://localhost:5000/v2.0
+
+We will deploy it to a ``test`` container under the folder
+``hello``::
+
+   $ zpm deploy hello.zar test/hello
+   deploying hello.zar
+   found token: MIIGjwYJKoZIhvcNAQcC...
+   found Swift: http://localhost:8080/v1/account
+   uploading 398 bytes to test/hello/hello.zar
+   updated test/hello/hello.zar succesfully
+
+For testing, you can execute the job after it has been deployed::
+
+   $ zpm deploy hello.zar test/hello --execute
+   deploying hello.zar
+   found token: MIIGjwYJKoZIhvcNAQcC...
+   found Swift: http://localhost:8080/v1/account
+   uploading 398 bytes to test/hello/hello.zar
+   updated test/hello/hello.zar succesfully
+   job template:
+   [{'exec': {'args': '/hello.py', 'path': u'file://python2.7:python'},
+     'file_list': [{'device': u'python2.7'},
+                   {'device': u'stdout'},
+                   {'device': 'image',
+                    'path': u'swift://account/test/hello/hello.zar'}],
+     'name': u'hello'}]
+   executing
+   <Response [200]>
+   Hello from ZeroVM!
+
+There currently no support for executing the application later. `Issue
+#37 <issue37_>`_ deals with that.
+
+.. _json: http://www.json.org/
+.. _issue37: https://github.com/zerovm/zpm/issues/37

zpmlib/commands.py

@@ -92,7 +92,11 @@ def new(args):
 
 @command
 def bundle(args):
-    """Bundle a ZeroVM application"""
+    """Bundle a ZeroVM application
+
+    This command creates a ZAR using the instructions in ``zar.json``.
+    The file is read from the project root.
+    """
     root = zpm.find_project_root()
     zpm.bundle_project(root)
 
@@ -146,7 +150,19 @@ def translate_args(cmdline):
 @arg('--os-password', default=os.environ.get('OS_PASSWORD'),
      help='OpenStack password. Defaults to $OS_PASSWORD.')
 def deploy(args):
-    """Deploy a ZeroVM application"""
+    """Deploy a ZeroVM application
+
+    This deploys a zar onto Swift. The zar can be one you have
+    downloaded or produced yourself :ref:`zpm-bundle`.
+
+    You will need to know the Swift authentication URL, username,
+    password, and tenant name. These can be supplied with command line
+    flags (see below) or you can set the corresponding environment
+    variables. The environment variables are the same as the ones used
+    by the `Swift command line tool <http://docs.openstack.org/
+    user-guide/content/swift_commands.html>`_, so if you're already
+    using that to upload files to Swift, you will be ready to go.
+    """
     print('deploying %s' % args.zar)
 
     tar = tarfile.open(args.zar)