From 9c2cb8871a620ba4717a1f25565d4eed05528d3b Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Tue, 18 Mar 2014 14:07:38 +0100 Subject: [PATCH 1/6] doc: extract docstrings from zpm commands --- doc/commands.rst | 6 ++++++ doc/conf.py | 15 ++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/commands.rst b/doc/commands.rst index 0f03d9c..f78d6f1 100644 --- a/doc/commands.rst +++ b/doc/commands.rst @@ -8,6 +8,8 @@ The ``zpm`` script has the following top-level commands: ``zpm new`` ----------- +.. autocommand:: zpmlib.commands.new + .. argparse:: :module: zpmlib.commands :func: set_up_arg_parser @@ -18,6 +20,8 @@ The ``zpm`` script has the following top-level commands: ``zpm deploy`` -------------- +.. autocommand:: zpmlib.commands.deploy + .. argparse:: :module: zpmlib.commands :func: set_up_arg_parser @@ -28,6 +32,8 @@ The ``zpm`` script has the following top-level commands: ``zpm bundle`` -------------- +.. autocommand:: zpmlib.commands.bundle + .. argparse:: :module: zpmlib.commands :func: set_up_arg_parser diff --git a/doc/conf.py b/doc/conf.py index 88467f6..efbb60b 100644 --- a/doc/conf.py +++ b/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 From 9a04ad3dbbc41edeeba5858a4fd060e8c0004136 Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Tue, 18 Mar 2014 14:38:23 +0100 Subject: [PATCH 2/6] doc: add anchors for zpm commands --- doc/commands.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/commands.rst b/doc/commands.rst index f78d6f1..6468654 100644 --- a/doc/commands.rst +++ b/doc/commands.rst @@ -5,6 +5,8 @@ ZPM Commands The ``zpm`` script has the following top-level commands: +.. _zpm-new: + ``zpm new`` ----------- @@ -17,6 +19,9 @@ The ``zpm`` script has the following top-level commands: :path: new +.. _zpm-deploy: + + ``zpm deploy`` -------------- @@ -29,6 +34,8 @@ The ``zpm`` script has the following top-level commands: :path: deploy +.. _zpm-bundle: + ``zpm bundle`` -------------- From 6361e9d221ab2ffc626f6f40e6c3bdfe1a87c59d Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Tue, 18 Mar 2014 14:38:36 +0100 Subject: [PATCH 3/6] commands: expand docstrings slightly --- zpmlib/commands.py | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/zpmlib/commands.py b/zpmlib/commands.py index d095d32..644cb4e 100644 --- a/zpmlib/commands.py +++ b/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,16 @@ 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. + """ print('deploying %s' % args.zar) tar = tarfile.open(args.zar) From dd3436d39bbd6a2562646e51d544117995f8426f Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Tue, 18 Mar 2014 16:36:37 +0100 Subject: [PATCH 4/6] deploy: link to Swift command line tool --- zpmlib/commands.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/zpmlib/commands.py b/zpmlib/commands.py index 644cb4e..e4804e9 100644 --- a/zpmlib/commands.py +++ b/zpmlib/commands.py @@ -158,7 +158,10 @@ def deploy(args): 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. + variables. The environment variables are the same as the ones used + by the `Swift command line tool `_, so if you're already + using that to upload files to Swift, you will be ready to go. """ print('deploying %s' % args.zar) From 1f1a43b9d9f310ed6f09ae8a07eb423c266ccafd Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Wed, 19 Mar 2014 08:37:57 +0100 Subject: [PATCH 5/6] doc: shorten main page title --- doc/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index b0c3db9..d8a87cd 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,8 +3,8 @@ 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: From 96b84182efcc30fd4892ff8e0798df2a1ff396ce Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Wed, 19 Mar 2014 10:49:47 +0100 Subject: [PATCH 6/6] doc: add introduction document This describes how to bundle and deploy a very simple "Hello World" program. It should of course be extended and probably split into more logical sections. --- doc/index.rst | 1 + doc/intro.rst | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 doc/intro.rst diff --git a/doc/index.rst b/doc/index.rst index d8a87cd..ad2b789 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,6 +11,7 @@ Contents: .. toctree:: :maxdepth: 2 + intro commands diff --git a/doc/intro.rst b/doc/intro.rst new file mode 100644 index 0000000..24413e0 --- /dev/null +++ b/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 ", + "Version": "0.1" + }, + "help" : { + "description": "A small \"Hello World\" app." + }, + "bundling": [ + "hello.py" + ] + } + +The file is in `JSON format `_ 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 + + Hello from ZeroVM! + +There currently no support for executing the application later. `Issue +#37 `_ deals with that. + +.. _json: http://www.json.org/ +.. _issue37: https://github.com/zerovm/zpm/issues/37