[spp] [PATCH 0/4] Revise help messages of commands and documentation

[spp] [PATCH 0/4] Revise help messages of commands and documentation

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Revise help messages of SPP controller for updating old, adding new and
correcting wrong descriptions. Documents of commands are also revised
in this update.

Yasufumi Ogawa (4):
  controller: revise help messages
  docs: update primary command reference
  docs: update secondary command reference
  docs: update common command reference

 docs/guides/commands/common.rst    |  55 ++++++++++-----
 docs/guides/commands/primary.rst   |  29 ++++----
 docs/guides/commands/secondary.rst |  84 ++++++++++++++---------
 src/controller/shell.py            | 134 ++++++++++++++++++++++++-------------
 4 files changed, 199 insertions(+), 103 deletions(-)

-- 
2.7.4

[spp] [PATCH 1/4] controller: revise help messages

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Revise help messages of SPP controller for updating old, adding new and
correcting wrong descriptions.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 src/controller/shell.py | 134 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 89 insertions(+), 45 deletions(-)

diff --git a/src/controller/shell.py b/src/controller/shell.py
index 8fb5a1a..3e0ca00 100644
--- a/src/controller/shell.py
+++ b/src/controller/shell.py
@@ -18,7 +18,7 @@ from . import topo
 
 
 class Shell(cmd.Cmd, object):
-    """SPP command prompt"""
+    """SPP command prompt."""
 
     hist_file = '.spp_history'
 
@@ -51,7 +51,7 @@ class Shell(cmd.Cmd, object):
         readline.write_history_file(hist_file)
 
     def default(self, line):
-        """Define defualt behaviour
+        """Define defualt behaviour.
 
         If user input is commend styled, controller simply echo
         as a comment.
@@ -64,7 +64,7 @@ class Shell(cmd.Cmd, object):
             super(Shell, self).default(line)
 
     def emptyline(self):
-        """Do nothin for empty input
+        """Do nothin for empty input.
 
         It override Cmd.emptyline() which runs previous input as default
         to do nothing.
@@ -91,7 +91,7 @@ class Shell(cmd.Cmd, object):
                     self.hist_file)
 
     def close_all_secondary(self):
-        """Terminate all secondary processes"""
+        """Terminate all secondary processes."""
 
         tmp_list = []
         for i in spp_common.SECONDARY_LIST:
@@ -101,10 +101,14 @@ class Shell(cmd.Cmd, object):
         spp_common.SECONDARY_COUNT = 0
 
     def get_status(self):
-        """Return status of primary and secondary processes
+        """Return the status of SPP processes.
 
-        It is called from do_status() method and return primary status
-        and a list of secondary processes as status.
+        Show the number of each of SPP processes running on.
+
+        spp > status
+        Soft Patch Panel Status :
+        primary: 1
+        secondary count: 2
         """
 
         secondary = []
@@ -118,7 +122,7 @@ class Shell(cmd.Cmd, object):
         return stat
 
     def print_status(self):
-        """Display information about connected clients"""
+        """Display information about connected clients."""
 
         print("Soft Patch Panel Status :")
         print("primary: %d" % spp_common.PRIMARY)  # it is 1 if PRIMA == True
@@ -357,7 +361,7 @@ class Shell(cmd.Cmd, object):
         self.response(self.CMD_OK, json.dumps(stat))
 
     def do_pri(self, command):
-        """Send command to primary process
+        """Send a command to primary process.
 
         Spp primary takes sub commands.
 
@@ -392,14 +396,20 @@ class Shell(cmd.Cmd, object):
         return completions
 
     def do_sec(self, arg):
-        """Send command to secondary process
+        """Send a command to secondary process specified with ID.
 
         SPP secondary process is specified with secondary ID and takes
         sub commands.
 
-        spp > sec 1;status
-        spp > sec 1;add ring 0
-        spp > sec 1;patch 0 2
+        spp > sec 1; status
+        spp > sec 1; add ring:0
+        spp > sec 1; patch phy:0 ring:0
+
+        You can refer all of sub commands by pressing TAB after
+        'sec 1;'.
+
+        spp > sec 1;  # press TAB
+        add     del     exit    forward patch   status  stop
         """
 
         # remove unwanted spaces to avoid invalid command error
@@ -470,14 +480,13 @@ class Shell(cmd.Cmd, object):
             print(e)
 
     def do_record(self, fname):
-        """Save commands to a log file
+        """Save commands as a recipe file.
 
-        Save command history to a log file for loading from playback
-        command later as a config file.
-        Config is a series of SPP command and you can also create it
-        from scratch without playback command.
+        Save all of commands to a specified file as a recipe. This file
+        is reloaded with 'playback' command later. You can also edit
+        the recipe by hand to customize.
 
-        spp > record path/to/file
+        spp > record path/to/recipe_file
         """
 
         if fname == '':
@@ -490,12 +499,12 @@ class Shell(cmd.Cmd, object):
         return common.compl_common(text, line)
 
     def do_playback(self, fname):
-        """Load a config file to reproduce network configuration
+        """Setup a network configuration from recipe file.
 
-        Config is a series of SPP command and you can also create it
-        from scratch without playback command.
+        Recipe is a file describing a series of SPP command to setup
+        a network configuration.
 
-        spp > playback path/to/config
+        spp > playback path/to/recipe_file
         """
 
         if fname == '':
@@ -520,7 +529,7 @@ class Shell(cmd.Cmd, object):
         return common.compl_common(text, line)
 
     def do_pwd(self, args):
-        """Show corrent directory
+        """Show corrent directory.
 
         It behaves as UNIX's pwd command.
 
@@ -530,7 +539,7 @@ class Shell(cmd.Cmd, object):
         print(os.getcwd())
 
     def do_ls(self, args):
-        """Show a list of specified directory
+        """Show a list of specified directory.
 
         It behaves as UNIX's ls command.
 
@@ -547,7 +556,7 @@ class Shell(cmd.Cmd, object):
         return common.compl_common(text, line)
 
     def do_cd(self, args):
-        """Change current directory
+        """Change current directory.
 
         spp > cd path/to/dir
         """
@@ -562,9 +571,10 @@ class Shell(cmd.Cmd, object):
         return common.compl_common(text, line, 'directory')
 
     def do_mkdir(self, args):
-        """Create a new directory
+        """Create a new directory.
 
-        It behaves as 'mkdir -p'.
+        It behaves as 'mkdir -p' which means that you can create sub
+        directories at once.
 
         spp > mkdir path/to/dir
         """
@@ -576,9 +586,10 @@ class Shell(cmd.Cmd, object):
         return common.compl_common(text, line)
 
     def do_bye(self, arg):
-        """Terminate SPP processes and controller
+        """Terminate SPP processes and controller.
 
-        It also terminates logging if you activate recording.
+        There are three usages for terminating processes.
+        It terminates logging if you activated recording.
 
         (1) Terminate secondary processes
         spp > bye sec
@@ -627,7 +638,10 @@ class Shell(cmd.Cmd, object):
             print("No such a directory.")
 
     def do_redo(self, args):
-        """Execute command of index of history."""
+        """Execute command of index of history.
+
+        spp > redo 5  # exec 5th command in the history
+        """
 
         idx = int(args)
         cmdline = None
@@ -651,12 +665,16 @@ class Shell(cmd.Cmd, object):
                     self.hist_file)
 
     def do_history(self, arg):
-        """Show history.
+        """Show command history.
 
         spp > history
           1  ls
           2  cat file.txt
           ...
+
+        Command history is recorded in a file named '.spp_history'.
+        It does not add some command which are no meaning for history.
+        'bye', 'exit', 'history', 'redo'
         """
 
         # flush all of history to the hist_file.
@@ -688,7 +706,7 @@ class Shell(cmd.Cmd, object):
         return common.compl_common(text, line)
 
     def do_less(self, arg):
-        """View contents of a file
+        """View contents of a file.
 
         spp > less file
         """
@@ -702,11 +720,12 @@ class Shell(cmd.Cmd, object):
         return common.compl_common(text, line)
 
     def do_exit(self, args):
-        """Terminate SPP controller
+        """Terminate SPP controller process.
 
-        It is an alias for bye command and same as bye command.
+        It is an alias of bye command to terminate controller.
 
         spp > exit
+        Thank you for using Soft Patch Panel
         """
 
         self.close()
@@ -714,29 +733,45 @@ class Shell(cmd.Cmd, object):
         return True
 
     def do_inspect(self, args):
+        """Print attributes of Shell for debugging.
+
+        This command is intended to be used by developers to show the
+        inside of the object of Shell class.
+
+        spp > inspect
+        {'cmdqueue': [],
+         'completekey': 'tab',
+         'completion_matches': ['inspect'],
+         'lastcmd': 'inspect',
+         'old_completer': None,
+         'stdin': <open file '<stdin>', mode 'r' at 0x7fe96bddf0c0>,
+         'stdout': <open file '<stdout>', mode 'w' at 0x7fe96bddf150>}
+
+        """
+
         from pprint import pprint
         if args == '':
             pprint(vars(self))
 
     def terms_topo_subgraph(self):
-        """Define terms of topo_subgraph command"""
+        """Define terms of topo_subgraph command."""
 
         return ['add', 'del']
 
     def do_topo_subgraph(self, args):
-        """Subgarph manager for topo
+        """Edit subgarph for topo command.
 
-        Subgraph is a group of object defined in dot language.
-        For topo command, it is used for grouping resources of each
-        of VM or container to topology be more understandable.
+        Subgraph is a group of object defined in dot language. For topo
+        command, it is used for grouping resources of each of VM or
+        container to topology be more understandable.
 
-        Add subgraph labeled 'vm1'.
+        (1) Add subgraph labeled 'vm1'.
         spp > topo_subgraph add vm1 vhost:1;vhost:2
 
-        Delete subgraph 'vm1'.
+        (2) Delete subgraph 'vm1'.
         spp > topo_subgraph del vm1
 
-        To show subgraphs, run topo_subgraph without args.
+        (3) Show subgraphs by running topo_subgraph without args.
         spp > topo_subgraph
         label: vm1	subgraph: "vhost:1;vhost:2"
         """
@@ -801,6 +836,15 @@ class Shell(cmd.Cmd, object):
             pass
 
     def do_topo_resize(self, args):
+        """Change the size of the image of topo command.
+
+        You can specify the size by percentage or ratio.
+
+        spp > topo resize 60%  # percentage
+        spp > topo resize 0.6  # ratio
+
+        """
+
         if args == '':
             print(self.topo_size)
         else:
@@ -816,7 +860,7 @@ class Shell(cmd.Cmd, object):
                 print(self.topo_size)
 
     def do_topo(self, args):
-        """Output network topology
+        """Output network topology.
 
         Support four types of output.
         * terminal (but very few terminals supporting to display images)
@@ -900,7 +944,7 @@ class Shell(cmd.Cmd, object):
             pass
 
     def do_load_cmd(self, args):
-        """Load command plugin
+        """Load command plugin.
 
         Path of plugin file is 'spp/src/controller/command'.
 
-- 
2.7.4

[spp] [PATCH 2/4] docs: update primary command reference

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Update description of primary commands.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/commands/primary.rst | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/docs/guides/commands/primary.rst b/docs/guides/commands/primary.rst
index 0a338e9..85c1c68 100644
--- a/docs/guides/commands/primary.rst
+++ b/docs/guides/commands/primary.rst
@@ -38,29 +38,35 @@ Primary process is managed with ``pri`` command.
 status
 ------
 
-Show status of primary.
+Show forwarding statistics of each of ports.
 
 .. code-block:: console
 
-    spp > pri status
-    recv:('127.0.0.1', 50524):{Server Running}
-
+    spp > pri; status
+    Physical Ports:
+      ID          rx          tx     tx_drop  mac_addr
+       0    78932932    78932931           1  56:48:4f:53:54:00
+    Ring Ports:
+      ID          rx          tx     rx_drop     tx_drop
+       0       89283       89283           0           0
+       1        9208        9203           0           5
+       ...
 
 exit
 ----
 
-Terminate primary.
+Terminate primary process.
 
 .. code-block:: console
 
-    spp > pri exit
-    closing:('127.0.0.1', 50524)
+    spp > pri; exit
 
 .. note::
 
-    You should not use this command because terminating primary before
-    secondaries may cause an error.
-    You shold use ``bye`` command instead of ``pri exit``.
+    You should not use this command if one or more secondary processes
+    are still running because terminating primary before secondaries may
+    cause an error. You shold use ``bye`` command instead of
+    ``pri; exit``.
 
 clear
 -----
@@ -69,5 +75,4 @@ Clear statistics.
 
 .. code-block:: console
 
-    spp > pri clear
-    recv:('127.0.0.1', 50524):{clear stats}
+    spp > pri; clear
-- 
2.7.4

[spp] [PATCH 3/4] docs: update secondary command reference

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Update description of secondary ommands.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/commands/secondary.rst | 84 ++++++++++++++++++++++++--------------
 1 file changed, 53 insertions(+), 31 deletions(-)

diff --git a/docs/guides/commands/secondary.rst b/docs/guides/commands/secondary.rst
index d3566ad..0c4d417 100644
--- a/docs/guides/commands/secondary.rst
+++ b/docs/guides/commands/secondary.rst
@@ -29,7 +29,7 @@
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 Secondary Commands
-======================
+==================
 
 Each of secondary processes is managed with ``sec`` command.
 It is for sending sub commands to secondary with specific ID called
@@ -44,48 +44,70 @@ owned by secondary process.
 
     spp > sec [SEC_ID];[SUB_CMD]
 
+All of Sub commands are referred with ``help`` command.
+
+.. code-block:: console
+
+    spp > help sec
+
+    Send a command to secondary process specified with ID.
+
+        SPP secondary process is specified with secondary ID and takes
+        sub commands.
+
+        spp > sec 1; status
+        spp > sec 1; add ring:0
+        spp > sec 1; patch phy:0 ring:0
+
+        You can refer all of sub commands by pressing TAB after
+        'sec 1;'.
+
+        spp > sec 1;  # press TAB
+        add     del     exit    forward patch   status  stop
 
 status
 ------
 
-Show running status and resources.
+Show running status and ports assigned to the process. If a port is
+patched to other port, source and destination ports are shown, or only
+source if it is not patched.
 
 .. code-block:: console
 
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0 -> ring:0
+      - phy:1
 
 
 add
 ---
 
-Add a PMD to the secondary with resource ID.
+Add a port to the secondary with resource ID.
 
-Adding ring 0 by
+For example, adding ``ring:0`` by
 
 .. code-block:: console
 
-    spp> sec 1;add ring 0
+    spp> sec 1; add ring:0
 
-Or adding vhost 0 by
+Or adding ``vhost:0`` by
 
 .. code-block:: console
 
-    spp> sec 1;add vhost 0
+    spp> sec 1; add vhost:0
 
 
 patch
 ------
 
 Create a path between two ports, source and destination ports.
-This command just creates path and does not start forwarding.
+This command just creates a path and does not start forwarding.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 ring:0
+    spp > sec 1; patch phy:0 ring:0
 
 
 forward
@@ -95,18 +117,18 @@ Start forwarding.
 
 .. code-block:: console
 
-    spp > sec 1;forward
+    spp > sec 1; forward
 
 Running status is changed from ``idling`` to ``running`` by
 executing it.
 
 .. code-block:: console
 
-    spp > sec 1;status
-    status: running
-    ports:
-      - 'phy:0'
-      - 'phy:1'
+    spp > sec 1; status
+    - status: running
+    - ports:
+      - phy:0
+      - phy:1
 
 
 stop
@@ -116,36 +138,36 @@ Stop forwarding.
 
 .. code-block:: console
 
-    spp > sec 1;stop
+    spp > sec 1; stop
 
 Running status is changed from ``running`` to ``idling`` by
 executing it.
 
 .. code-block:: console
 
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
 
 
 del
 ---
 
-Delete PMD added by ``add`` subcommand from the secondary.
+Delete a port from the secondary.
 
 .. code-block:: console
 
-    spp> sec 1;del ring 0
+    spp> sec 1; del ring:0
 
 
 exit
 ----
 
-Terminate the secondary. For terminating all secondaries, use ``bye sec``
-command instead of it.
+Terminate the secondary. For terminating all secondaries,
+use ``bye sec`` command instead of it.
 
 .. code-block:: console
 
-    spp> sec 1;exit
+    spp> sec 1; exit
-- 
2.7.4

[spp] [PATCH 4/4] docs: update common command reference

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Update description of common commands.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/commands/common.rst | 55 ++++++++++++++++++++++++++++++-----------
 1 file changed, 40 insertions(+), 15 deletions(-)

diff --git a/docs/guides/commands/common.rst b/docs/guides/commands/common.rst
index ebd1fa1..36573f5 100644
--- a/docs/guides/commands/common.rst
+++ b/docs/guides/commands/common.rst
@@ -30,7 +30,7 @@
 
 
 Common Commands
-====================
+===============
 
 status
 ------
@@ -48,16 +48,34 @@ It also show a list of secondary IDs
     Connected secondary id: 2
 
 
+playback
+--------
+
+Restore network configuration from a recipe file which defines a set
+of SPP commands.
+You can prepare a recipe file by using ``record`` command or editing
+file by hand.
+
+It is recommended to use extension ``.rcp`` to be self-sxplanatory as
+a recipe, although you can use any of extensions such as ``.txt`` or
+``.log``.
+
+.. code-block:: console
+
+    spp > playback /path/to/my.rcp
+
+
 record
 ------
 
-Start recording user's input and create a history file for ``playback``
-commnad.
-Recording is stopped by executing ``exit`` or ``playback`` command.
+Start recording user's input and create a recipe file for loading
+from ``playback`` commnad.
+Recording recipe is stopped by executing ``exit`` or ``playback``
+command.
 
 .. code-block:: console
 
-    spp > record 2nfv_uni.config
+    spp > record /path/to/my.rcp
 
 .. note::
 
@@ -67,21 +85,28 @@ Recording is stopped by executing ``exit`` or ``playback`` command.
     next relase.
 
 
-playback
---------
+history
+-------
 
-Restore configuration from a config file.
-Content of config file is just a series of SPP commnad.
-You prepare a config file by using ``record`` command or editing a text
-file by hand.
+Show command history. Command history is recorded in a file named
+``$HOME/.spp_history``. It does not add some command which are no
+meaning for history, ``bye``, ``exit``, ``history`` and ``redo``.
 
-It is recommended to use extension ``.config`` to be self-sxplanatory
-as a config, although you can use any of extensions such as ``.txt`` or
-``.log``.
+.. code-block:: console
+
+    spp > history
+      1  ls
+      2  cat file.txt
+
+
+redo
+----
+
+Execute command of index of history.
 
 .. code-block:: console
 
-    spp> playback 2nfv_uni.config
+    spp > redo 5  # exec 5th command in the history
 
 
 pwd
-- 
2.7.4