Rev 2426: Command objects can now declare related help topics by having _see_also in file:///home/robertc/source/baz/see-also/
Robert Collins
robertc at robertcollins.net
Wed Apr 18 09:40:55 BST 2007
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())
More information about the bazaar-commits
mailing list