doc: Add documentation on running interactively

This adds a file that explains how to run Rumba interactively, as it
may be bothersome to swap it out each time.

4 files changed, 55 insertions, 2 deletions

diff --git a/doc/emulab.rst b/doc/emulab.rst
index 77ac3d0..8549677 100644
--- a/doc/emulab.rst
+++ b/doc/emulab.rst
@@ -10,7 +10,7 @@ though a public key was added to the emulab interface. In this case
 a workaround is to start an ssh-agent and add the public key there. ::
 
     $ eval `ssh-agent`
-    $ ssh-add /home/user/.ssh/id_rsa.pub
+    $ ssh-add $HOME/.ssh/id_rsa.pub
 
 .. automodule:: rumba.testbeds.emulab
     :member-order: bysource
diff --git a/doc/general.rst b/doc/general.rst
index cf8c577..a04afdd 100644
--- a/doc/general.rst
+++ b/doc/general.rst
@@ -4,3 +4,4 @@ General usage
 .. toctree::
    workflow
    installation
+   interactive
diff --git a/doc/interactive.rst b/doc/interactive.rst
new file mode 100644
index 0000000..88eaf2d
--- /dev/null
+++ b/doc/interactive.rst
@@ -0,0 +1,52 @@
+Running Rumba interactively
+*****************************
+
+As Rumba is a Python framework, it is possible to run experiments
+interactively. In order to do so, simply run Python in a terminal and
+import the script. An example is given below.
+
+First start by creating a new Python file (file.py) wherein the
+Recursive Network is defined, the testbed and the experiment. In the
+example, let's have 2 nodes with an Ethernet layer between them and
+run that on the jFed testbed with a custom install of the Ouroboros
+prototype. ::
+
+  #!/usr/bin/env python
+
+  from rumba.model import *
+  import rumba.testbeds.jfed as jfed
+  import rumba.prototypes.ouroboros as our
+
+  e1 = ShimEthDIF("e1")
+
+  a = Node("a", difs = [e1])
+
+  b = Node("b", difs = [e1])
+
+  tb = jfed.Testbed(exp_name = "test",
+                    cert_file = "/location/of/cert.pem",
+                    username = "username")
+
+  exp = our.Experiment(tb,
+                       nodes = [a, b],
+                       git_repo='/location/of/custom/ouroboros/git/repo')
+
+Now that we have the Python file with our experiment defined, we can
+run it interactively. ::
+
+  [user@computer ~]$ python
+  Python 3.7.2 (default, Dec 29 2018, 21:15:15)
+  [GCC 8.2.1 20181127] on linux
+  Type "help", "copyright", "credits" or "license" for more information.
+  >>> from file import *
+
+Once the experiment is loaded, it is possible to execute functions. ::
+
+  >>> exp.swap_in()
+  >>> exp.install_prototype()
+  >>> exp.bootstrap_prototype()
+  >>> exp.terminate_prototype()
+  >>> exp.swap_out()
+
+A common use case would be to install the prototype, bootstrap it,
+debug the experiment, terminate the prototype, install it again, ...
diff --git a/doc/jfed.rst b/doc/jfed.rst
index b9f2822..d78c6b7 100644
--- a/doc/jfed.rst
+++ b/doc/jfed.rst
@@ -25,7 +25,7 @@ jFed CLI as well.) In order to start an SSH agent and to add the
 certificate, type the following commands: ::
 
     $ eval `ssh-agent`
-    $ ssh-add /home/morty/cert.pem
+    $ ssh-add $HOME/cert.pem
 
 Pay attention to run your rumba script in the same terminal used
 for the previous commands, without changing the user (e.g. using su