Clean up tutorial, split into #1,#2 etc.

.gitignore

@@ -0,0 +1 @@
+build/

creating_service/nstack_toolkit.rst

@@ -13,20 +13,7 @@ It provides a range of commands used to interact with your code and the nstack s
 Getting Started
 ^^^^^^^^^^^^^^^
 
-Firstly, install the CLI and requirements by following the instructions in :ref:`getting_started_installation`. 
-
-**Quick Install**
-
-.. code:: bash
-
-    curl https://nstack.com/install/install.sh | sh
-    
-**Update**
-
-.. code:: bash
-
-    nstack --update
-    **TODO**
+Firstly, install the CLI and requirements by following the instructions in :ref:`CLI installation <CLI_installation>`. 
 
 Usage
 -----
@@ -103,7 +90,7 @@ By default it creates a service in your stack that has a single ``add`` function
 
 The ``init`` command also creates a git repo and commits the files be default.
 
-``build``
+``build`` [building/deploying]
 ^^^^^^^^^
 **TODO-mandeep**
 
@@ -119,23 +106,13 @@ Option          Description
 
 Builds the image on your hosted nstack instance. This command is usually unneeded as the ``boot`` command runs a build if needed.
 
-``deploy``
+``run/start`` [run/starting]
 ^^^^^^^^^
 **TODO-mandeep**
 
 .. code:: bash
 
-    $ nstack boot 
-
-Deploys your service onto your nstack server. Once a service is deployed, it can be attached to event-sources. 
-
-``trigger``
-^^^^^^^^^
-**TODO-mandeep**
-
-.. code:: bash
-
-    $ nstack trigger service event-source [entry=]
+    $ nstack run service [event-source] [entry=]
 
 ============    ===========
 Option          Description
@@ -145,7 +122,7 @@ Option          Description
 
 Attaches your service to an event-source. When an event is recieved, your service runs. 
 
-``ps``
+``ps`` [listing running service+event]
 ^^^^^^^^^^^^^^^^
 
 .. code:: bash
@@ -155,7 +132,7 @@ Attaches your service to an event-source. When an event is recieved, your servic
 
 Shows a list of all services which are *active* on your nstack server (i.e. they are been bound to an event-source). You can think of these as 'processes'. This is distincy from ``ls``, which shows you the services which have been deployed and are available to run. 
 
-``kill``
+``kill`` [stop a running service+event]
 ^^^^^^^^^^^^^^^^
 
 .. code:: bash
@@ -165,7 +142,7 @@ Shows a list of all services which are *active* on your nstack server (i.e. they
 
 Stop a running process.
 
-``ls``
+``ls`` [listing available/built services]
 ^^^^^^^^^^
 
 .. code:: bash
@@ -175,7 +152,7 @@ Stop a running process.
 
 Shows a list of all available services on your nstack server. These may or may not be running processes (i.e. attached to event-sources).
 
-``rm``
+``rm`` [remove service]
 ^^^^^^^^^^^^^^^^
 
 .. code:: bash
@@ -186,3 +163,6 @@ Shows a list of all available services on your nstack server. These may or may n
 Deletes a service which from your nstack host. 
 
 
+``status`` [logs/status of a service]
+
+

getting_started/index.rst

@@ -4,9 +4,10 @@
 Getting Started
 ***************
 
-In this section we describe how you can install the nstack toolkit, and use it in the :ref:`getting_started_tutorial` to create, deploy and call a simple service.
+In this section we describe how to install nstack, and how to deploy your first service!
 
 .. toctree::
+   :maxdepth: 1
 
    installation
    tutorial

getting_started/installation.rst

@@ -1,46 +1,50 @@
 .. _getting_started_installation:
 
+=====================
 Platform Installation
 =====================
 
-
-****
 Introduction
-****
-nstack is comprised of two parts: your nstack machine, which lives as a virtual appliance on your local network or cloud provider, and the nstack toolkit.
+^^^^^
 
-The nstack machine is where your services are built, compiled, and executed, whilst the nstack toolkit is used to push services and administer the machine.
+nstack is comprised of two parts: 
 
-As the machine is an appliance, you can run it locally (using something like kvm or virtualbox), or it can be hosted on your cloud provider of choice. You are not limited to one machine: many users have a machine on their cloud provider for production services, and a local machine for testing or staging.
+- **nstack engine** is a virtual machine which can be hosted locally or on your cloud provider. It is where your services are deployed to, compiled, and where they run.
+- **nstack toolkit** is a local binary which controls the nstack engine. It is used to deploy microservices from your machine to your engine.
 
-***
-Installation
-***
+.. _machine_installation:
 
-..Note: All releases can be found on nstack's `release page <http://nstack.com/install>`_. 
+Engine Installation
+^^^^^^
 
-To install the machine, browse to nstack's `release page <http://nstack.com/install>`_. We have helpers to let you install it to AWS, or you can download the .iso and host it where you please. 
+To install the machine, browse to nstack's `release page <http://nstack.com/install>`_. We have helpers to let you install it to AWS, or you can download the .iso and host it elsewhere. As it is a VM, it can run on your local machine (using something like KVM or VirtualBox) 
 
- * :ref:`_aws_installation`
- * :ref:`_manual_installation`
+ * :ref:`AWS Installation <aws_installation>`
+ * :ref:`Manual Installation <manual_installation>`
 
 .. _aws_installation:
 
-***
-AWS Installation
-***
+**AWS Installation**
 
-**TODO**
+nstack provides a CloudFormation template to install nstack to AWS. 
 
-nstack provides a CloudFormation template to install to your AWS vpc. 
+.. _manual_installation:
 
-***
-Manual Installation
-***
+**Manual Installation**
 
 **TODO**
 
 nstack provides an .iso which you can host on your virtual machine of choice.
 
+.. _toolk_installation:
+
+Toolkit Installation
+^^^^^
+
+To install the nstack CLI, you will need to download it from the website. To do this:
+
+.. code-block:: bash
 
+	$ curl https://nstack.com/install/cli | sh
 
+This will take you through the install process. 

getting_started/tutorial.rst

@@ -1,96 +1,119 @@
-.. _getting_started_tutorial:
+.. _tutorial1:
 
-Tutorial
+Tutorial #1 -- Deploying a Service
 ========
 
-This tutorial briefly describes how you can develop, test and deploy a simple service on nstack. This one will only take a few minutes, but services can be as complex as you like. Firstly, check you've installed nstack as described in :ref:`getting_started_installation`. 
+This tutorial walks you through deploying a simple service on nstack; as a first example, we're using a demo service which squares a number (don't worry, we'll be adding to it in due course!)
+
+Before we begin, check you've installed nstack as described in :ref:`getting_started_installation`, and attached your toolkit to your nstack machine.
 
 Creating a Service
 ------------------
 
 Initialise a Project
 ^^^^^^^^^^^^^^^^^^^^
 
-We start by initialising a nstack service, let's call this one ``demo-python``. 
+We start by initialising a nstack service, with the `--remote` flag. This simply pulls a service from a GitHub repository. 
 
 .. code-block:: bash
 
     # create and cd into the project directory
-    [~]$ mkdir demo-python
-    [~]$ cd demo-python
-    # run nstack init to initialise the project
-    [demo-python]$ nstack init python
-
-The ``nstack init`` command takes one parameter, which is the language you'd like to build your service in. Here it is Python (short for Python 3). When you run init, nstack will create a working skeleton project for you to quickly get started with, including an initial Git commit.
+    [~]$ nstack init --remote=https://github.com/nstack-oss/example-service
+    [~]$ cd example-service
 
-This contains all the files a nstack service needs, already configured using sensible defaults for the chosen system.
+This already contains all the files a nstack service needs.
 
 .. code-block:: bash
 
     [demo-python]$ ls
-    api.idl  app.py  nstack.yaml requirements.txt README.md
+    api.idl  app.py  nstack.yaml requirements.txt 
+
+In the next section, we'll walk through these files:
+
+Service structure
+^^^^^^^^^^^^^^^^^^^^
+``app.py``
+^^^^^^^^^^
+
+This is a simple python class which comprises your service. As you can see, we're not doing anything particularly exciting here, but this could be as complex as you please.
 
-There are several files here - and we'll cover the important ones in the following sections. They are all discussed further in :ref:`creating_structure_yaml`.
-The ``nstack.yaml`` is a *YAML* file containing configuration regarding dependencies. More information regarding its parameters can be found in :ref:`creating_structure_hutfile`.
+.. code-block:: python
+	#!/usr/bin/env python3
+	# -*- coding: utf-8 -*-
+	import nstack	
 
-.. There is a README.md markdown file to further describe your service.
+	class ExampleService(nstack.Service):
+		def square(number):
+			return number * number
 
 
-Signature
+
+``nstack.yaml``
 ^^^^^^^^^
+The ``nstack.yaml`` is a *YAML* file containing configuration. Here, it includes any dependencies your service has, the stack (or runtime) for your service, and any operating system dependencies (which are *yum* packages). Because our service is boring at the moment, we don't have any dependencies (yet!)
+
+.. code-block:: yaml
+	
+	# Service name (a combination of lower case letters, numbers, and dashes)
+	name: image-process
 
-The ``api.idl`` interface-definition (IDL) file describes our service interface. This is a place to specify the inputs into your code; or, to think of it the other way around, the parts of your code you want to expose. 
+	# The language runtime
+	stack: python
 
-One of the features of nstack is that your inputs can (optionally) be type-checked. This means you can make sure that your code is getting the right input. Additionally, knowing the inputs and outputs of a service allows you to compose them together intelligently. We like to think of it as bringing the power of statically-typed languages to infrastructure.
+``api.idl``
+^^^^^^^^^
+
+The ``api.idl`` is an interface-definition (IDL) file which describes our service interface. This is a place to specify the inputs into your code; or, to think of it the other way around, the parts of your code you want to expose. 
 
-**TODO**
+.. code-block:: java
 
+	ExampleService {
+		sqrt(int) : int
+	}
 
-Code
-^^^^
+One of the features of nstack is that your inputs is type-checked. Here, we are saying we want to expose our function ``sqrt`` which takes an ``int`` and returns an ``int``.
 
-Having defined the interface into our service, we can now write the code. Your app code lives in ``app.py`` (or ``app.js`` for JS, and so on), as follows:
+``requirements.txt``
 
-**TODO**
+This is the dependencies for Python's package manager. There aren't any yet, so this file is empty.
 
 
-Hosting your Service
+Building your service with nstack-engine
 --------------------
 
-Now you've developed your service you can host it on your local nstack install to test it, or you can go straight ahead and deploy live to your nstack server.
+When you compile or run a service, it is run on the nstack engine (which is a Linux virtual machine). Make sure you've installed nstack as described in :ref:`getting_started_installation`. To compile it with the engine, run ``nstack build``
 
-Hosting locally
-^^^^^^^^^^^^^^^
+.. code-block:: bash
 
-**TODO**
+	$ nstack build
+	[Success] Your service is live at 1.1.1.1
 
+Once a service is live, it can be run or run in response to various event sources. To simply run our ``square`` function we can: 
 
-Hosting on nstack-cloud
-^^^^^^^^^^^^^^^^^^^
+.. code-block:: bash
 
-**TODO**
+	$ nstack run square("3")
+	[Error] Service expected 'int' but received 'string' 
 
+Oops! As we specified in our ``api.idl``, our ``square`` function should take an int and return an int. We accidentally passed a string ("3" instead of 3), so it errored. 
 
-Using your Service
-------------------
+Let's try again:
 
-Once your nstack service is live, it can react to events.
+.. code-block:: bash
 
-Events can be third-party event-sources (such as a Kafka stream or a RabbitMQ queue) or internal nstack events, such as our HTTP Gateway or Scheduler. 
+	$ nstack run square(3)
+	[Success] Service successfully ran with result `9 : Int`
 
-When an event comes in, the whole nstack infrastructure is abstracted away from your service code. From this point of view, it's as simple as executing a function call.
+Great! 
 
-Read more about using services in :ref:`using_index`
+Next steps
+-------------------
 
-Calling a service
-^^^^^^^^^^^^^^^^^
+Great! Now we're ready to add some dependencies and build something a bit more 'real-world' 
 
-**TODO**
+:ref:`tutorial2`
 
-Further Information
--------------------
 
-This was a simple example, but you can build anything you can in a normal server: you can even package up existing legacy infrastructure into event-driven services. See the :ref:`examples_index` to see how services have been built.
 
 
 

getting_started/tutorial2.rst

@@ -0,0 +1,4 @@
+.. _tutorial2:
+
+Tutorial #2 - Dependencies 	
+^^^^^^^^^

index.rst

@@ -3,10 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-How the documentation is organized
+nstack Documentation
 ====================================
 
-Check out :ref:`getting_started_index` for a quick guide to both using and creating services on nstack.
+Welcome! To jump right now, check out :ref:`tutorial1` for a quick guide to using and creating a service on nstack.
 
 Please let us know at docs@nstack.com if anything is unclear or you find a mistake. Better still, submit a pull-request using the link at the top-right. 
 

introduction.rst

@@ -1,10 +1,17 @@
-Introduction
+Introduction / What is nstack?
 ************
 
-nstack is a framework to construct, compile, and compose 'algebraic' microservices.
+.. _what_is_nstack: 
+**What is nstack?**
 
 nstack turns a piece of code (such as a function, a class, or a libary) into a lightweight microservice that can be bound to an event-source (such as a stream, a message queue, or a scheduler). On an event, nstack intelligently distributes execution of your service and routes messages into your code.
 
-As a developer, you can focus exclusively on writing your core business-logic, while nstack makes performant, intelligent decisions about your services, and solves many common problems out of the box.
+**Why is this useful?**
 
+nstack automates all infrastructure, protocols, and middleware: a simple class or library becomes a fully-fledged cloud service that can be attached to events. As a developer, you can focus exclusively on writing your core business-logic, while nstack makes performant, intelligent decisions about your services, and solves many common problems out of the box (monitoring, logging, scheduling, type-checking, etc.)
 
+**How does this relate to microservices and 'serverless'?**
+
+Although they are similar abstractions, nstack takes microservices and 'serverless' a step further by treating services like objects in a statically-typed programming language. We believe in taking the lessons and research from building languages and applying them to infrastructure.
+
+If you're still confused, please email info@nstack.com; we'd love to chat!