doc/_ext: parse prefix and args for command signature

unlike the commands defined by C++, the commands defined by python
now uses "prefix" and "args" properties of elements in COMMAND class
attribute to define their command and arguments. the "cmd" property is
still available for the ceph CLI.

but the ceph_command sphinx extension should now use "prefix" and "args"
for printing out the usage of commands implemented using python. in
this change, the extension is updated to read "prefix" and "args"
properties of command defined by python modules.

Signed-off-by: Kefu Chai <kchai@redhat.com>

diff --git a/doc/_ext/ceph_commands.py b/doc/_ext/ceph_commands.py
index 39dcde08822ad233fb4ced4b032fa4a9717a48c3..685dd2933f6d37fc8c9951bbc70e7dc5b847a1b5 100644 (file)
--- a/doc/_ext/ceph_commands.py
+++ b/doc/_ext/ceph_commands.py
@@ -134,9 +134,9 @@ class CmdParam(object):
 
 
 class CmdCommand(object):
-    def __init__(self, sig, desc, module=None, perm=None, flags=0, poll=None):
-        self.sig = [s for s in sig if isinstance(s, str)]
-        self.params = sorted([CmdParam(**s) for s in sig if not isinstance(s, str)],
+    def __init__(self, prefix, args, desc, module=None, perm=None, flags=0, poll=None):
+        self.prefix = prefix
+        self.params = sorted([CmdParam(**arg) for arg in args],
                              key=lambda p: p.req, reverse=True)
         self.help = desc
         self.module = module
@@ -144,9 +144,6 @@ class CmdCommand(object):
         self.flags = Flags(flags)
         self.needs_overload = False
 
-    def prefix(self):
-        return ' '.join(self.sig)
-
     def is_reasonably_simple(self):
         if len(self.params) > 3:
             return False
@@ -156,22 +153,28 @@ class CmdCommand(object):
 
     def mk_bash_example(self):
         simple = self.is_reasonably_simple()
-        line = ' '.join(['ceph', self.prefix()] + [p.mk_bash_example(simple) for p in self.params])
+        line = ' '.join(['ceph', self.prefix] + [p.mk_bash_example(simple) for p in self.params])
         return line
 
 
 class Sig:
     @staticmethod
-    def _param_to_sig(p):
+    def _parse_arg_desc(desc):
         try:
-            return {kv.split('=')[0]: kv.split('=')[1] for kv in p.split(',') if kv}
+            return {kv.split('=')[0]: kv.split('=')[1] for kv in desc.split(',') if kv}
         except IndexError:
-            return p
+            return desc
+
+    @staticmethod
+    def parse_cmd(cmd):
+        parsed = [Sig._parse_arg_desc(s) or s for s in cmd.split()]
+        prefix = [s for s in parsed if isinstance(s, str)]
+        params = [s for s in parsed if not isinstance(s, str)]
+        return ' '.join(prefix), params
 
     @staticmethod
-    def from_cmd(cmd):
-        sig = cmd.split()
-        return [Sig._param_to_sig(s) or s for s in sig]
+    def parse_args(args):
+        return [Sig._parse_arg_desc(arg) for arg in args.split()]
 
 
 TEMPLATE = '''
@@ -179,8 +182,8 @@ TEMPLATE = '''
 
 {% for command in commands %}
 
-{{ command.prefix() }}
-{{ command.prefix() | length * '^' }}
+{{ command.prefix }}
+{{ command.prefix | length * '^' }}
 
 {{ command.help | wordwrap(70)}}
 
@@ -292,8 +295,11 @@ class CephMgrCommands(Directive):
     def _normalize_command(self, command):
         if 'handler' in command:
             del command['handler']
-        command['sig'] = Sig.from_cmd(command['cmd'])
-        del command['cmd']
+        if 'cmd' in command:
+            command['prefix'], command['args'] = Sig.parse_cmd(command['cmd'])
+            del command['cmd']
+        else:
+            command['args'] = Sig.parse_args(command['args'])
         command['flags'] = (1 << 3)
         command['module'] = 'mgr'
         return command
@@ -315,7 +321,7 @@ class CephMgrCommands(Directive):
         commands = sum([self._collect_module_commands(name) for name in modules], [])
         cmds = [CmdCommand(**self._normalize_command(c)) for c in commands]
         cmds = [cmd for cmd in cmds if 'hidden' not in cmd.flags]
-        cmds = sorted(cmds, key=lambda cmd: cmd.sig)
+        cmds = sorted(cmds, key=lambda cmd: cmd.prefix)
         self._render_cmds(cmds)
         return []
 
@@ -396,7 +402,7 @@ class CephMonCommands(Directive):
     def _normalize_command(self, command):
         if 'handler' in command:
             del command['handler']
-        command['sig'] = Sig.from_cmd(command['cmd'])
+        command['prefix'], command['args'] = Sig.parse_cmd(command['cmd'])
         del command['cmd']
         return command
 
@@ -413,7 +419,7 @@ class CephMonCommands(Directive):
         commands = self._parse_headers(headers)
         cmds = [CmdCommand(**self._normalize_command(c)) for c in commands]
         cmds = [cmd for cmd in cmds if 'hidden' not in cmd.flags]
-        cmds = sorted(cmds, key=lambda cmd: cmd.sig)
+        cmds = sorted(cmds, key=lambda cmd: cmd.prefix)
         self._render_cmds(cmds)
         return []