Updates to use new help feature

- updated some other plugins to use the new help feature
- bumped release
- updated example notebook for remote reference viewer control

ginga/rv/Control.py

@@ -335,17 +335,20 @@ def error_wrap(self, method, *args, **kwargs):
             self.logger.error(errmsg)
             self.gui_do(self.show_error, errmsg, raisetab=True)
 
-    def help(self, text=None, text_kind='url', trim_pfx=0):
+    def help_text(self, name, text, text_kind='plain', trim_pfx=0):
         """
         Provide help text for the user.
 
         Parameters
         ----------
-        text : str or None (optional)
-            The text to show.  Should be a URL, HTML text or RST text
+        name : str
+            Category of help to show.
+
+        text : str
+            The text to show.  Should be plain, HTML or RST text
 
         text_kind : str (optional)
-            One of 'url', 'html', 'rst'.  Default is 'url'.
+            One of 'plain', 'html', 'rst'.  Default is 'plain'.
 
         trim_pfx : int (optional)
             Number of spaces to trim off the beginning of each line of text.
@@ -356,34 +359,38 @@ def help(self, text=None, text_kind='url', trim_pfx=0):
         displayed in a plain text widget.
         """
 
-        if text is not None:
-            if trim_pfx > 0:
-                # caller wants to trim some space off the front
-                # of each line
-                text = toolbox.trim_prefix(text, trim_pfx)
+        if trim_pfx > 0:
+            # caller wants to trim some space off the front
+            # of each line
+            text = toolbox.trim_prefix(text, trim_pfx)
 
-            if text_kind in ('html', 'url'):
-                pass
+        if text_kind == 'rst':
+            # try to convert RST to HTML using docutils
+            try:
+                overrides = {'input_encoding': 'ascii',
+                             'output_encoding': 'utf-8'}
+                text_html = publish_string(text, writer_name='html',
+                                           settings_overrides=overrides)
+                # docutils produces 'bytes' output, but webkit needs
+                # a utf-8 string
+                text = text_html.decode('utf-8')
+                text_kind = 'html'
 
-            elif text_kind == 'rst':
-                # try to convert RST to HTML using docutils
-                try:
-                    overrides = {'input_encoding': 'ascii',
-                                 'output_encoding': 'utf-8'}
-                    text_html = publish_string(text, writer_name='html',
-                                               settings_overrides=overrides)
-                    # docutils produces 'bytes' output, but webkit needs
-                    # a utf-8 string
-                    text = text_html.decode('utf-8')
-
-                except Exception as e:
-                    self.logger.error("Error converting help text to HTML: %s" % (
-                        str(e)))
-                    # revert to showing RST as plain text
-                    return self.show_help_text('Help', text)
+            except Exception as e:
+                self.logger.error("Error converting help text to HTML: %s" % (
+                    str(e)))
+                # revert to showing RST as plain text
 
-            else:
-                raise ValueError("I don't know how to display text of kind '%s'" % (text_kind))
+        else:
+            raise ValueError("I don't know how to display text of kind '%s'" % (text_kind))
+
+        if text_kind == 'html':
+            self.help(text=text, text_kind='html')
+
+        else:
+            self.show_help_text(name, text)
+
+    def help(self, text=None, text_kind='url'):
 
         if not self.gpmon.has_plugin('WBrowser'):
             return self.show_error("help() requires 'WBrowser' plugin")

ginga/rv/plugins/Blink.py

@@ -11,6 +11,8 @@
 
 class Blink(GingaPlugin.LocalPlugin):
     """
+    Blink
+    =====
     Blink switches through the images shown in a channel at a rate
     chosen by the user.  Alternatively, it can switch between channels
     in the main workspace.  In both cases, the primary purpose is to
@@ -130,7 +132,7 @@ def build_gui(self, container):
 
     def help(self):
         name = str(self).capitalize()
-        self.fv.show_help_text(name, self.__doc__)
+        self.fv.help_text(name, self.__doc__, text_kind='rst', trim_pfx=4)
 
     def close(self):
         if self.fitsimage is None:

ginga/rv/plugins/Crosshair.py

@@ -9,6 +9,8 @@
 
 class Crosshair(GingaPlugin.LocalPlugin):
     """
+    Crosshair
+    =========
     Crosshair is a simple plugin to draw crosshairs labeled with the
     position of the cross in pixels coordinates, WCS coordinates or
     data value at the cross position.
@@ -107,7 +109,7 @@ def set_format(self):
 
     def help(self):
         name = str(self).capitalize()
-        self.fv.show_help_text(name, self.__doc__)
+        self.fv.help_text(name, self.__doc__, text_kind='rst', trim_pfx=4)
 
     def close(self):
         self.fv.stop_local_plugin(self.chname, str(self))

ginga/rv/plugins/Cuts.py

@@ -364,7 +364,7 @@ def axes_callback_handler(self, chkbox, pos):
 
     def help(self):
         name = str(self).capitalize()
-        self.fv.help(text=self.__doc__, text_kind='rst', trim_pfx=4)
+        self.fv.help_text(name, self.__doc__, text_kind='rst', trim_pfx=4)
 
     def select_cut(self, tag):
         self.cutstag = tag

ginga/rv/plugins/Histogram.py

@@ -14,6 +14,8 @@
 
 class Histogram(GingaPlugin.LocalPlugin):
     """
+    Histogram
+    =========
     Histogram plots a histogram for a region drawn in the image, or for the
     entire image.
 
@@ -212,7 +214,7 @@ def close(self):
 
     def help(self):
         name = str(self).capitalize()
-        self.fv.show_help_text(name, self.__doc__)
+        self.fv.help_text(name, self.__doc__, text_kind='rst', trim_pfx=4)
 
     def start(self):
         self.plot.set_titles(rtitle="Histogram")

ginga/rv/plugins/Overlays.py

@@ -11,6 +11,8 @@
 
 class Overlays(GingaPlugin.LocalPlugin):
     """
+    Overlays
+    ========
     A plugin for generating color overlays representing under- and
     overexposure in the loaded image.
 
@@ -133,7 +135,7 @@ def build_gui(self, container):
 
     def help(self):
         name = str(self).capitalize()
-        self.fv.show_help_text(name, self.__doc__)
+        self.fv.help_text(name, self.__doc__, text_kind='rst', trim_pfx=4)
 
     def close(self):
         self.fv.stop_local_plugin(self.chname, str(self))

ginga/rv/plugins/PixTable.py

@@ -12,6 +12,8 @@
 
 class PixTable(GingaPlugin.LocalPlugin):
     """
+    PixTable
+    ========
     PixTable provides a way to check or monitor the pixel values in
     a region.
 
@@ -320,7 +322,7 @@ def close(self):
 
     def help(self):
         name = str(self).capitalize()
-        self.fv.show_help_text(name, self.__doc__)
+        self.fv.help_text(name, self.__doc__, text_kind='rst', trim_pfx=4)
 
     def start(self):
         # insert layer if it is not already

ginga/rv/plugins/Ruler.py

@@ -9,14 +9,16 @@
 
 class Ruler(GingaPlugin.LocalPlugin):
     """
+    Ruler
+    =====
     Ruler is a simple plugin designed to measure distances on an image.
     It does this by calculating a spherical triangulation via WCS mapping
     of three points defined by a single line drawn on the image.  By default,
     the distance is shown in arcminutes of sky, but using the Units control
     it can be changed to show degrees or pixel distance instead.
 
     [ Should you want "sticky rulers", use the Drawing plugin (and choose
-      "Ruler" as the drawing type). ]
+    "Ruler" as the drawing type). ]
 
     Usage
     -----
@@ -148,7 +150,7 @@ def close(self):
 
     def help(self):
         name = str(self).capitalize()
-        self.fv.show_help_text(name, self.__doc__)
+        self.fv.help_text(name, self.__doc__, text_kind='rst', trim_pfx=4)
 
     def start(self):
         # start ruler drawing operation

setup.cfg

@@ -26,7 +26,7 @@ license = BSD
 url = http://ejeschke.github.com/ginga
 edit_on_github = False
 github_project = ejeschke/ginga/
-version = 2.6.3.dev
+version = 2.6.3
 keywords = scientific image viewer numpy toolkit astronomy FITS
 classifiers =
     Intended Audience :: Science/Research,