SVN: zdaemon/trunk/src/zdaemon/ Sort out where help docs come from.

Log message for revision 99067:
  Sort out where help docs come from.
  The original intent was that the __doc__ of the __main__ module was used in no overridden by passing doc as a keyword argument to realize.
  However, as buildout generates scripts, the __doc__ of __main__ will always be blank.
  So, changed the mechanism to use __doc__ of the options class and set the __doc__ of all the options classes to the __doc__ of their containing module, giving the original intended effect.

Changed:
  U   zdaemon/trunk/src/zdaemon/tests/testzdoptions.py
  U   zdaemon/trunk/src/zdaemon/tests/testzdrun.py
  U   zdaemon/trunk/src/zdaemon/zdctl.py
  U   zdaemon/trunk/src/zdaemon/zdoptions.py
  U   zdaemon/trunk/src/zdaemon/zdrun.py

-=-
Modified: zdaemon/trunk/src/zdaemon/tests/testzdoptions.py
===================================================================
--- zdaemon/trunk/src/zdaemon/tests/testzdoptions.py	2009-04-09 22:36:51 UTC (rev 99066)
+++ zdaemon/trunk/src/zdaemon/tests/testzdoptions.py	2009-04-10 00:30:16 UTC (rev 99067)
@@ -81,58 +81,64 @@
             options.realize([arg, configfile])
             self.assertEqual(options.configfile, configfile)
 
-    def test_help(self):
-        # __main__.__doc__ is used as the default source of the help
-        # text; specific text can also be provided in the `doc`
-        # keyword arg to `realize()`.
-        import __main__
-        old_doc = __main__.__doc__
-        __main__.__doc__ = "Example help text 1."
-        try:
-            for arg in "-h", "--h", "--help":
-                for doc in (None, "Example help text 2."):
-                    options = self.OptionsClass()
-                    try:
-                        self.save_streams()
-                        try:
-                            if doc:
-                                options.realize([arg], doc=doc)
-                            else:
-                                options.realize([arg])
-                        finally:
-                            self.restore_streams()
-                    except SystemExit, err:
-                        self.assertEqual(err.code, 0)
-                    else:
-                        self.fail("%s didn't call sys.exit()" % repr(arg))
-                    helptext = self.stdout.getvalue()
-                    self.assertEqual(helptext, doc or __main__.__doc__)
-        finally:
-            __main__.__doc__ = old_doc
+    # The original intent was that the docstring of whatever module is
+    # __main__ would be used as help documentation.
+    # Because of the way buildout generates scripts, this will always
+    # be an empty string.
+    # So, we now use the __doc__ of the options class being used.
 
-    def test_no_help(self):
-        # Test that zdoptions doesn't die when __main__.__doc__ is None.
-        import __main__
-        old_doc = __main__.__doc__
-        __main__.__doc__ = None
-        try:
-            for arg in "-h", "--h", "--help":
-                options = self.OptionsClass()
+    def help_test_helper(self,optionsclass,kw,expected):
+        for arg in "-h", "--h", "--help":
+            options = optionsclass()
+            try:
+                self.save_streams()
                 try:
-                    self.save_streams()
-                    try:
-                        options.realize([arg])
-                    finally:
-                        self.restore_streams()
-                except SystemExit, err:
-                    self.assertEqual(err.code, 0)
-                else:
-                    self.fail("%s didn't call sys.exit()" % repr(arg))
-                helptext = self.stdout.getvalue()
-                self.assertEqual(helptext, "No help available.")
-        finally:
-            __main__.__doc__ = old_doc
+                    options.realize([arg],**kw)
+                finally:
+                    self.restore_streams()
+            except SystemExit, err:
+                self.assertEqual(err.code, 0)
+            else:
+                self.fail("%s didn't call sys.exit()" % repr(arg))
+            helptext = self.stdout.getvalue()
+            self.assertEqual(helptext, expected)
+        
+    def test_default_help(self):
+        # test what happens when the subclass doesn't do anything
+        # with __doc__
+        self.help_test_helper(self.OptionsClass,{},'No help available.')
 
+    def test_default_help_with_doc_kw(self):
+        # test what happens when the subclass doesn't do anything
+        # with __doc__, but doc is supplied to realize
+        self.help_test_helper(self.OptionsClass,{'doc':'Example help'},'Example help')
+
+    def test_no_help(self):
+        # test what happens when the subclass has None for __doc__
+        class NoHelp(self.OptionsClass):
+            __doc__ = None
+        self.help_test_helper(NoHelp,{},'No help available.')
+        
+    def test_no_help_with_doc_kw(self):
+        # test what happens when the subclass has None for __doc__,
+        # but doc is supplied to realize
+        class NoHelp(self.OptionsClass):
+            __doc__ = None
+        self.help_test_helper(NoHelp,{'doc':'Example help'},'Example help')
+
+    def test_help(self):
+        # test what happens when the subclass has None for __doc__
+        class HasHelp(self.OptionsClass):
+            __doc__ = 'Some help'
+        self.help_test_helper(HasHelp,{},'Some help')
+        
+    def test_no_help_with_doc_kw(self):
+        # test what happens when the subclass has None for __doc__,
+        # but doc is supplied to realize
+        class HasHelp(self.OptionsClass):
+            __doc__ = 'Some help'
+        self.help_test_helper(HasHelp,{'doc':'Example help'},'Example help')
+
     def test_unrecognized(self):
         # Check that we get an error for an unrecognized option
         self.check_exit_code(self.OptionsClass(), ["-/"])

Modified: zdaemon/trunk/src/zdaemon/tests/testzdrun.py
===================================================================
--- zdaemon/trunk/src/zdaemon/tests/testzdrun.py	2009-04-09 22:36:51 UTC (rev 99066)
+++ zdaemon/trunk/src/zdaemon/tests/testzdrun.py	2009-04-10 00:30:16 UTC (rev 99067)
@@ -91,11 +91,14 @@
         ##os.system("PYTHONPATH=%s %s %s -s %s %s &" %
         ##    (self.ppath, self.python, self.zdrun, self.zdsock, args))
 
-    def _run(self, args, cmdclass=None):
+    def _run(self, args, cmdclass=None, module=zdctl):
         if type(args) is type(""):
             args = args.split()
+        kw = {}
+        if cmdclass:
+            kw['cmdclass']=cmdclass
         try:
-            zdctl.main(["-s", self.zdsock] + args, cmdclass=cmdclass)
+            module.main(["-s", self.zdsock] + args, **kw)
         except SystemExit:
             pass
 
@@ -110,21 +113,13 @@
         self.rundaemon(["echo", "-n"])
         self.expect = ""
 
-    def testHelp(self):
-        # XXX We shouldn't mutate and leave our change in!
-        import __main__
-        if not __main__.__doc__:
-            __main__.__doc__ = "Example help text."
-        self._run("-h")
-        self.expect = __main__.__doc__
+    def test_help_zdrun(self):
+        self._run("-h",module=zdrun)
+        self.expect = zdrun.__doc__
 
-    def testNoHelp(self):
-        # XXX We shouldn't mutate and leave our change in!
-        import __main__
-        if __main__.__doc__:
-            __main__.__doc__ = None
+    def test_help_zdctl(self):
         self._run("-h")
-        self.expect = "No help available."
+        self.expect = zdctl.__doc__
 
     def testOptionsSysArgv(self):
         # Check that options are parsed from sys.argv by default

Modified: zdaemon/trunk/src/zdaemon/zdctl.py
===================================================================
--- zdaemon/trunk/src/zdaemon/zdctl.py	2009-04-09 22:36:51 UTC (rev 99066)
+++ zdaemon/trunk/src/zdaemon/zdctl.py	2009-04-10 00:30:16 UTC (rev 99067)
@@ -76,7 +76,9 @@
 
 
 class ZDCtlOptions(RunnerOptions):
-
+    
+    __doc__ = __doc__
+    
     positional_args_allowed = True
 
     def __init__(self):
@@ -101,8 +103,6 @@
 
     def realize(self, *args, **kwds):
         
-        kwds['doc']=kwds.get('doc',__doc__)
-        
         RunnerOptions.realize(self, *args, **kwds)
 
         # Maybe the config file requires -i or positional args

Modified: zdaemon/trunk/src/zdaemon/zdoptions.py
===================================================================
--- zdaemon/trunk/src/zdaemon/zdoptions.py	2009-04-09 22:36:51 UTC (rev 99066)
+++ zdaemon/trunk/src/zdaemon/zdoptions.py	2009-04-10 00:30:16 UTC (rev 99067)
@@ -199,7 +199,7 @@
 
         progname -- the program name (default is sys.argv[0])
 
-        doc      -- usage message (default is __main__.__doc__)
+        doc      -- usage message (default is __doc__ of the options class)
         """
 
          # Provide dynamic default method arguments
@@ -215,11 +215,8 @@
             except (AttributeError, IndexError):
                 progname = 'zope'
 
-        if doc is None:
-            import __main__
-            doc = __main__.__doc__
         self.progname = progname
-        self.doc = doc
+        self.doc = doc or self.__doc__
 
         self.options = []
         self.args = []

Modified: zdaemon/trunk/src/zdaemon/zdrun.py
===================================================================
--- zdaemon/trunk/src/zdaemon/zdrun.py	2009-04-09 22:36:51 UTC (rev 99066)
+++ zdaemon/trunk/src/zdaemon/zdrun.py	2009-04-10 00:30:16 UTC (rev 99067)
@@ -86,6 +86,8 @@
 
 class ZDRunOptions(RunnerOptions):
 
+    __doc__ = __doc__
+    
     positional_args_allowed = 1
     logsectionname = "runner.eventlog"
     program = None