Rev 2453: Teach Command.get_help_text to show additional help cross references when supplied. in file:///home/robertc/source/baz/help-contexts/

[Robert Collins]

At file:///home/robertc/source/baz/help-contexts/

------------------------------------------------------------
revno: 2453
revision-id: robertc at robertcollins.net-20070420035406-e68xf089otkpo7xx
parent: robertc at robertcollins.net-20070420033954-afes0jishuy9cf6k
committer: Robert Collins <robertc at robertcollins.net>
branch nick: help-contexts
timestamp: Fri 2007-04-20 13:54:06 +1000
message:
  Teach Command.get_help_text to show additional help cross references when supplied.
modified:
  bzrlib/commands.py             bzr.py-20050309040720-d10f4714595cf8c3
  bzrlib/tests/test_commands.py  test_command.py-20051019190109-3b17be0f52eaa7a8
  bzrlib/tests/test_help.py      test_help.py-20070419045354-6q6rq15j9e2n5fna-1
=== modified file 'bzrlib/commands.py'
--- a/bzrlib/commands.py	2007-04-20 03:19:49 +0000
+++ b/bzrlib/commands.py	2007-04-20 03:54:06 +0000
@@ -260,8 +260,12 @@
         s = s[:-1]
         return s
 
-    def get_help_text(self):
-        """Return a text string with help for this command."""
+    def get_help_text(self, additional_see_also=None):
+        """Return a text string with help for this command.
+        
+        :param additional_see_also: Additional help topics to be
+            cross-referenced.
+        """
         doc = self.help()
         if doc is None:
             raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
@@ -285,21 +289,25 @@
             result += '\n'
         result += '\n'
         result += option.get_optparser(self.options()).format_option_help()
-        see_also = self.get_see_also()
+        see_also = self.get_see_also(additional_see_also)
         if see_also:
             result += '\nSee also: '
             result += ', '.join(see_also)
             result += '\n'
         return result
 
-    def get_see_also(self):
+    def get_see_also(self, additional_terms=None):
         """Return a list of help topics that are related to this ommand.
         
         The list is derived from the content of the _see_also attribute. Any
         duplicates are removed and the result is in lexical order.
+        :param additional_terms: Additional help topics to cross-reference.
         :return: A list of help topics.
         """
-        return sorted(set(getattr(self, '_see_also', [])))
+        see_also = set(getattr(self, '_see_also', []))
+        if additional_terms:
+            see_also.update(additional_terms)
+        return sorted(see_also)
 
     def options(self):
         """Return dict of valid options for this command.

=== modified file 'bzrlib/tests/test_commands.py'
--- a/bzrlib/tests/test_commands.py	2007-04-18 08:39:02 +0000
+++ b/bzrlib/tests/test_commands.py	2007-04-20 03:54:06 +0000
@@ -125,3 +125,12 @@
             _see_also = ['foo', 'bar']
         command = ACommand()
         self.assertEqual(['bar', 'foo'], command.get_see_also())
+
+    def test_additional_terms(self):
+        """Additional terms can be supplied and are deduped and sorted."""
+        class ACommand(commands.Command):
+            _see_also = ['foo', 'bar']
+        command = ACommand()
+        self.assertEqual(['bar', 'foo', 'gam'],
+            command.get_see_also(['gam', 'bar', 'gam']))
+

=== modified file 'bzrlib/tests/test_help.py'
--- a/bzrlib/tests/test_help.py	2007-04-20 03:39:54 +0000
+++ b/bzrlib/tests/test_help.py	2007-04-20 03:54:06 +0000
@@ -51,6 +51,29 @@
         helptext = cmd.get_help_text()
         self.assertStartsWith(helptext, 'usage:bzr Demo')
         self.assertEndsWith(helptext, 'show help message\n')
+
+    def test_command_with_additional_see_also(self):
+        class cmd_WithSeeAlso(commands.Command):
+            """A sample command."""
+            _see_also = ['foo', 'bar']
+        cmd = cmd_WithSeeAlso()
+        helptext = cmd.get_help_text(['gam'])
+        self.assertEndsWith(
+            helptext,
+            '  -h, --help  show help message\n'
+            '\n'
+            'See also: bar, foo, gam\n')
+
+    def test_command_only_additional_see_also(self):
+        class cmd_WithSeeAlso(commands.Command):
+            """A sample command."""
+        cmd = cmd_WithSeeAlso()
+        helptext = cmd.get_help_text(['gam'])
+        self.assertEndsWith(
+            helptext,
+            '  -h, --help  show help message\n'
+            '\n'
+            'See also: gam\n')
     
 
 class TestRegisteredTopic(tests.TestCase):