Rev 2426: Command objects can now declare related help topics by having _see_also in file:///home/robertc/source/baz/see-also/

[Robert Collins]

At file:///home/robertc/source/baz/see-also/

------------------------------------------------------------
revno: 2426
revision-id: robertc at robertcollins.net-20070418083902-4o66h9fk7zeisvwa
parent: pqm at pqm.ubuntu.com-20070417080415-5vn25svmf95ki88z
committer: Robert Collins <robertc at robertcollins.net>
branch nick: see-also
timestamp: Wed 2007-04-18 18:39:02 +1000
message:
  Command objects can now declare related help topics by having _see_also
  set to a list of related topic. Updated the HACKING guide entry on
  documentation to be more clear about how the help for commands is
  generated and to reference this new feature. (Robert Collins)
modified:
  HACKING                        HACKING-20050805200004-2a5dc975d870f78c
  NEWS                           NEWS-20050323055033-4e00b5db738777ff
  bzrlib/commands.py             bzr.py-20050309040720-d10f4714595cf8c3
  bzrlib/tests/test_commands.py  test_command.py-20051019190109-3b17be0f52eaa7a8
=== modified file 'HACKING'
--- a/HACKING	2007-04-11 10:46:19 +0000
+++ b/HACKING	2007-04-18 08:39:02 +0000
@@ -133,8 +133,19 @@
 Documentation
 =============
 
-If you change the behaviour of a command, please update its docstring
-in bzrlib/commands.py.  This is displayed by the 'bzr help' command.
+When you change bzrlib, please update the relevant documentation for the
+change you made: Changes to commands should update their help, and
+possibly end user tutorials; changes to the core library should be
+reflected in API documentation.
+
+Commands
+--------
+
+The docstring of a command is used by ``bzr help`` to generate help output
+for the command. The list 'takes_options' attribute on a command is used by
+``bzr help`` to document the options for the command - the command
+docstring does not need to document them. Finally, the '_see_also'
+attribute on a command can be used to reference other related help topics.
 
 NEWS file
 ---------

=== modified file 'NEWS'
--- a/NEWS	2007-04-17 07:09:43 +0000
+++ b/NEWS	2007-04-18 08:39:02 +0000
@@ -55,6 +55,9 @@
      instances of those objects can share a lock if it has the right token.
      (Andrew Bennetts, Robert Collins)
 
+    * Command objects can now declare related help topics by having _see_also
+      set to a list of related topic. (Robert Collins)
+
   BUGFIXES:
 
     * Don't fail bundle selftest if email has 'two' embedded.  

=== modified file 'bzrlib/commands.py'
--- a/bzrlib/commands.py	2007-03-21 01:34:41 +0000
+++ b/bzrlib/commands.py	2007-04-18 08:39:02 +0000
@@ -233,6 +233,15 @@
         if self.__doc__ == Command.__doc__:
             warn("No help message set for %r" % self)
 
+    def get_see_also(self):
+        """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.
+        :return: A list of help topics.
+        """
+        return sorted(set(getattr(self, '_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	2006-11-30 04:46:23 +0000
+++ b/bzrlib/tests/test_commands.py	2007-04-18 08:39:02 +0000
@@ -21,12 +21,13 @@
     commands,
     config,
     errors,
+    tests,
     )
 from bzrlib.commands import display_command
-from bzrlib.tests import TestCase, TestSkipped
-
-
-class TestCommands(TestCase):
+from bzrlib.tests import TestSkipped
+
+
+class TestCommands(tests.TestCase):
 
     def test_display_command(self):
         """EPIPE message is selectively suppressed"""
@@ -58,7 +59,7 @@
                           commands.run_bzr, ['log', u'--option\xb5'])
 
 
-class TestGetAlias(TestCase):
+class TestGetAlias(tests.TestCase):
 
     def _get_config(self, config_text):
         my_config = config.GlobalConfig()
@@ -93,3 +94,34 @@
             u"iam=whoami 'Erik B\u00e5gfors <erik at bagfors.nu>'\n")
         self.assertEqual([u'whoami', u'Erik B\u00e5gfors <erik at bagfors.nu>'],
                           commands.get_alias("iam", config=my_config))
+
+
+class TestSeeAlso(tests.TestCase):
+    """Tests for the see also functional of Command."""
+
+    def test_default_subclass_no_see_also(self):
+        class ACommand(commands.Command):
+            """A sample command."""
+        command = ACommand()
+        self.assertEqual([], command.get_see_also())
+
+    def test__see_also(self):
+        """When _see_also is defined, it sets the result of get_see_also()."""
+        class ACommand(commands.Command):
+            _see_also = ['bar', 'foo']
+        command = ACommand()
+        self.assertEqual(['bar', 'foo'], command.get_see_also())
+
+    def test_deduplication(self):
+        """Duplicates in _see_also are stripped out."""
+        class ACommand(commands.Command):
+            _see_also = ['foo', 'foo']
+        command = ACommand()
+        self.assertEqual(['foo'], command.get_see_also())
+
+    def test_sorted(self):
+        """_see_also is sorted by get_see_also."""
+        class ACommand(commands.Command):
+            _see_also = ['foo', 'bar']
+        command = ACommand()
+        self.assertEqual(['bar', 'foo'], command.get_see_also())