help, makeapi: specify module topic by name

Specify module topic by name rather than by name and summary. A topic
module of the topic name must exist. Summary is extracted from the
docstring of the topic module.

This changes makes topic handling more generic and consistent between
modules and commands.

https://fedorahosted.org/freeipa/ticket/4739

Reviewed-By: David Kupka <dkupka@redhat.com>

ipaclient/plugins/otptoken_yubikey.py

@@ -47,7 +47,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('otp', _('One time password commands'))
+topic = 'otp'
 
 
 @register()

ipalib/cli.py

@@ -701,7 +701,7 @@ class help(frontend.Local):
             module = importlib.import_module(module_name)
 
         doc = unicode(module.__doc__ or '').strip()
-        parent_topic = getattr(module, 'topic', [None])[0]
+        parent_topic = getattr(module, 'topic', None)
 
         return doc, parent_topic
 
@@ -733,8 +733,7 @@ class help(frontend.Local):
                     mcl = max((self._topics[topic_name][1], len(c.name)))
                     self._topics[topic_name][1] = mcl
                 else: # a module grouped in a topic
-                    m = '%s.%s' % (self._PLUGIN_BASE_MODULE, c.topic)
-                    topic = sys.modules[m].topic
+                    topic = self._get_topic(topic_name)
                     mod_name = c.topic
                     if topic_name in self._topics:
                         if mod_name in self._topics[topic_name][2]:
@@ -746,7 +745,9 @@ class help(frontend.Local):
                         mcl = max((self._topics[topic_name][2][mod_name][1], len(c.name)))
                         self._topics[topic_name][2][mod_name][1] = mcl
                     else:
-                        self._topics[topic_name] = [unicode(_(topic[1])), 0, {mod_name: [doc, 0, [c]]}]
+                        self._topics[topic_name] = [topic[0].split('\n', 1)[0],
+                                                    0,
+                                                    {mod_name: [doc, 0, [c]]}]
                         self._count_topic_mcl(topic_name, mod_name)
             else:
                 self._builtins.append(c)

ipalib/plugins/hbac.py

@@ -0,0 +1,7 @@
+#
+# Copyright (C) 2016  FreeIPA Contributors see COPYING for license
+#
+
+from ipalib.text import _
+
+__doc__ = _('Host-based access control commands')

ipalib/plugins/hbacrule.py

@@ -101,7 +101,7 @@ register = Registry()
 #   ipa hbacrule-add-accesstime --time='absolute 201012161032 ~ 201012161033' test1
 
 
-topic = ('hbac', _('Host-based access control commands'))
+topic = 'hbac'
 
 def validate_type(ugettext, type):
     if type.lower() == 'deny':

ipalib/plugins/hbacsvc.py

@@ -50,7 +50,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('hbac', _('Host based access control commands'))
+topic = 'hbac'
 
 @register()
 class hbacsvc(LDAPObject):

ipalib/plugins/hbacsvcgroup.py

@@ -53,7 +53,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('hbac', _('Host based access control commands'))
+topic = 'hbac'
 
 @register()
 class hbacsvcgroup(LDAPObject):

ipalib/plugins/otp.py

@@ -0,0 +1,7 @@
+#
+# Copyright (C) 2016  FreeIPA Contributors see COPYING for license
+#
+
+from ipalib.text import _
+
+__doc__ = _('One time password commands')

ipalib/plugins/otpconfig.py

@@ -49,7 +49,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('otp', _('One time password commands'))
+topic = 'otp'
 
 
 @register()

ipalib/plugins/otptoken.py

@@ -72,7 +72,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('otp', _('One time password commands'))
+topic = 'otp'
 
 TOKEN_TYPES = {
     u'totp': ['ipatokentotpclockoffset', 'ipatokentotptimestep'],

ipalib/plugins/sudo.py

@@ -0,0 +1,7 @@
+#
+# Copyright (C) 2016  FreeIPA Contributors see COPYING for license
+#
+
+from ipalib.text import _
+
+__doc__ = _('commands for controlling sudo configuration')

ipalib/plugins/sudocmd.py

@@ -47,7 +47,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('sudo', _('commands for controlling sudo configuration'))
+topic = 'sudo'
 
 @register()
 class sudocmd(LDAPObject):

ipalib/plugins/sudocmdgroup.py

@@ -56,7 +56,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('sudo', _('commands for controlling sudo configuration'))
+topic = 'sudo'
 
 @register()
 class sudocmdgroup(LDAPObject):

ipalib/plugins/sudorule.py

@@ -92,7 +92,7 @@ EXAMPLES:
 
 register = Registry()
 
-topic = ('sudo', _('Commands for controlling sudo configuration'))
+topic = 'sudo'
 
 
 def deprecated(attribute):

makeapi

@@ -166,24 +166,19 @@ def validate_doc():
         if getattr(cmd, 'NO_CLI', False):
             continue
 
-        if cmd.topic is not None:
-            # Have we processed this module yet?
-            if not topics.setdefault(cmd.topic, 0):
+        # Have we processed this module yet?
+        topic = cmd.topic
+        while topic is not None:
+            if not topics.setdefault(topic, 0):
                 # First time seeing this module, validate the module contents
-                module = 'ipalib.plugins.%s' % cmd.topic
+                module = 'ipalib.plugins.%s' % topic
                 try:
                     mod = sys.modules[module]
                 except KeyError:
                     mod = importlib.import_module(module)
 
                 # See if there is a module topic, if so validate it
-                topic = getattr(mod, 'topic', None)
-                if topic is not None:
-                    if not is_i18n(topic[1]):
-                        src_file = inspect.getsourcefile(cmd_class)
-                        n_missing_mod_i18n += 1
-                        print("%s: topic in module \"%s\" is not "
-                              "internationalized" % (src_file, module))
+                next_topic = getattr(mod, 'topic', None)
 
                 # Does the module have documentation?
                 if mod.__doc__ is None:
@@ -197,9 +192,13 @@ def validate_doc():
                     n_missing_mod_i18n += 1
                     print("%s: module \"%s\" doc is not internationalized" %
                           (src_file, module))
+            else:
+                next_topic = None
 
             # Increment the count of how many commands in this module
-            topics[cmd.topic] = topics[cmd.topic] + 1
+            topics[topic] = topics[topic] + 1
+
+            topic = next_topic
 
         # Does the command have documentation?
         if cmd.__doc__ is None: