From 41a0fce2b047dacc0e67972ca058c194caa1a51c Mon Sep 17 00:00:00 2001 From: Sander Vrijders Date: Thu, 29 Mar 2018 16:24:52 +0200 Subject: doc: Reorganize documentation This reorganizes the documentation somewhat to be more tutorial-styled. --- .gitlab-ci.yml | 2 +- doc/model.rst | 26 ++++++++++++++++++++++---- doc/prototype.rst | 8 ++++++++ doc/storyboard.rst | 3 +++ doc/testbed.rst | 8 ++++++++ doc/workflow.rst | 21 ++++++++++++--------- rumba/model.py | 4 +++- 7 files changed, 57 insertions(+), 15 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 313ad89..dad6f1d 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -17,4 +17,4 @@ pages: paths: - public only: - - doc + - master diff --git a/doc/model.rst b/doc/model.rst index b487263..1ced817 100644 --- a/doc/model.rst +++ b/doc/model.rst @@ -1,5 +1,23 @@ -Model -============= +Defining the recursive network +============================== -.. automodule:: rumba.model - :member-order: bysource +Experimenters can define their recursive network by using the building +blocks listed below. + +.. autoclass:: rumba.model.Node + +.. autoclass:: rumba.model.DIF + +.. autoclass:: rumba.model.NormalDIF + +.. autoclass:: rumba.model.ShimUDPDIF + +.. autoclass:: rumba.model.ShimEthDIF + +.. autoclass:: rumba.model.Distribution + +.. autoclass:: rumba.model.Delay + +.. autoclass:: rumba.model.Loss + +.. autoclass:: rumba.model.LinkQuality diff --git a/doc/prototype.rst b/doc/prototype.rst index 13b4547..a827dcb 100644 --- a/doc/prototype.rst +++ b/doc/prototype.rst @@ -1,6 +1,14 @@ Prototype plugins ------------------------- +Rumba provides a generic Experiment class that specific protoypes can +derive from. All prototypes have to re-implement the functions +provided by the base class. + +.. autoclass:: rumba.model.Experiment + +Specific implementations of the Testbed class: + .. toctree:: irati rlite diff --git a/doc/storyboard.rst b/doc/storyboard.rst index 085ea30..7d1f18c 100644 --- a/doc/storyboard.rst +++ b/doc/storyboard.rst @@ -1,5 +1,8 @@ Storyboard ============= +Experimenters can create a Storyboard to emulate real network traffic +to be run after the recursive network is up and running. + .. automodule:: rumba.storyboard :member-order: bysource diff --git a/doc/testbed.rst b/doc/testbed.rst index aca73b7..0158904 100644 --- a/doc/testbed.rst +++ b/doc/testbed.rst @@ -1,6 +1,14 @@ Testbed plugins ------------------------- +Rumba provides a generic Testbed class that specific implementations +can derive from. All testbeds have to re-implement the functions +provided by the base class. + +.. autoclass:: rumba.model.Testbed + +Specific implementations of the Testbed class: + .. toctree:: docker emulab diff --git a/doc/workflow.rst b/doc/workflow.rst index 672c33c..95f68c2 100644 --- a/doc/workflow.rst +++ b/doc/workflow.rst @@ -2,25 +2,28 @@ Workflow ************************ 1. Define the network graph, creating instances of model.Node and - model.DIF classes. + model.DIF classes. Experiments can import rumba.model to obtain all + Rumba classes needed to run an experiment. -2. Create an instance of a Testbed class. +2. Create an instance of a specific model.Testbed class (QEMU, Docker, + Local, Emulab or jFed). -3. Create an instance of the selected prototype.Experiment class, - passing the testbed instance and a list of Node instances. +3. Create an instance of the selected prototype.Experiment class + (Ouroboros, rlite, IRATI), passing the testbed instance and a list + of Node instances. 1. At the end of the base Experiment constructor, the generate function is called to generate information about per-node IPCPs, registrations and enrollment, ready to be - used by the plugins. + used by the prototype plugins. 4. Call methods on the prototype.Experiment instance: 1. swap_in() swaps the experiment in on the testbed, and fills in the missing information in the model. - 2. install_prototype() installs the chosen prototype on the - testbed. Currently an Ubuntu image is assumed. + 2. install_prototype() installs the chosen prototype on the testbed + (if necessary). Currently an Ubuntu image is assumed. 3. bootstrap_prototype() calls a prototype-specific setup function, to create the required IPCPs, perform registrations, @@ -28,7 +31,7 @@ Workflow 4. swap_out() swaps the experiment out of the testbed. -5. Run a Storyboard to emulate real network traffic. +5. Optionally run a Storyboard to emulate real network traffic. Accessing nodes after swap-in @@ -39,4 +42,4 @@ command (in the same terminal where ssh-agent was run in case of jFed): :: $ rumba-access $NODE_NAME -Where $NODE_NAME is the name of the node to access. \ No newline at end of file +Where $NODE_NAME is the name of the node to access. diff --git a/rumba/model.py b/rumba/model.py index 4c151e9..2d573f6 100644 --- a/rumba/model.py +++ b/rumba/model.py @@ -44,7 +44,8 @@ from rumba.elements.topology import ( LinkQuality, Delay, - Loss + Loss, + Distribution ) from rumba.elements.experimentation import ( @@ -72,6 +73,7 @@ __all__ = [ "LinkQuality", "Delay", "Loss", + "Distribution", # Experimentation "Experiment", -- cgit v1.2.3