[MERGE] updated help topics

[Martin Pool]

On  8 Nov 2006, John Arbash Meinel <john at arbash-meinel.com> wrote:

+1 with 2 corrections, well done.

> Well, I decided to get into this a bit, because I want to see it merged,
> and so I did 2 basic changes:
> 
> 1) Switched to using a subclass of Registry. As part of doing this, I
> realized that the current API wasn't what I would prefer. It was asking
> the registered functions to write to a file, rather than having them
> return a string. Which sort of fit with the old help api, but I don't
> really think is the best way of doing it.
> 
> For one, if you have a GUI, you don't really want to have to pass in
> StringIO just to get the help texts.
> 
> 2) Change from using RevisionSpec.__doc__ to using
> RevisionSpec.help_txt. As you say, it wasn't that hard to do. I went
> with 'help_txt' because 'help' is a builtin python command. (Although
> only really useful from the command line)
> 
> Attached is the new diff. I realize there are still some changes in
> builtins which might conflict, but I don't think they are serious.
> 
> Plus, in my long-term goals, I'd like to refactor builtins.py to a set
> of commands in bzrlib/commands/* which are all lazily registered. But
> I'm not quite there yet. :)

btw if you and Goffredo have read it that's probably enough review.

+from bzrlib import registry
+
+
+class HelpTopicRegistry(registry.Registry):
+    """A Regsitry customized for handling help topics."""

'Registry'

+
+    def register(self, topic, detail, summary):
+        """Register a new help topic.
+
+        :param topic: Name of documentation entry
+        :param detail: Function or string object providing detailed
+            documentation for topic.  Function interface is detail(topic).
+            This should return a text string of the detailed information.
+        :param summary: String providing single-line documentation for topic.
+        """
+        # The detail is stored as the 'object' and the 
+        super(HelpTopicRegistry, self).register(topic, detail, info=summary)
+
+    def register_lazy(self, topic, module_name, member_name, summary):
+        """Register a new help topic, and import the details on demand.
+
+        :param topic: Name of documentation entry
+        :param module_name: The module to find the detailed help.
+        :param member_name: The member of the module to use for detailed help.
+        :param summary: String providing single-line documentation for topic.
+        """
+        super(HelpTopicRegistry, self).register(topic, module_name,
+                                                member_name, info=summary)

Shouldn't the super call be to register_lazy?

-- 
Martin