diff --git a/doc/commands.rst b/doc/commands.rst index 0f03d9c..6468654 100644 --- a/doc/commands.rst +++ b/doc/commands.rst @@ -5,9 +5,13 @@ 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 @@ -15,9 +19,14 @@ The ``zpm`` script has the following top-level commands: :path: new +.. _zpm-deploy: + + ``zpm deploy`` -------------- +.. autocommand:: zpmlib.commands.deploy + .. argparse:: :module: zpmlib.commands :func: set_up_arg_parser @@ -25,9 +34,13 @@ The ``zpm`` script has the following top-level commands: :path: deploy +.. _zpm-bundle: + ``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 diff --git a/doc/index.rst b/doc/index.rst index b0c3db9..ad2b789 100644 --- a/doc/index.rst +++ b/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 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 diff --git a/zpmlib/commands.py b/zpmlib/commands.py index d095d32..e4804e9 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,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 `_, 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)