helper-level method to programmatically toggle API hints

CHANGES.rst

@@ -8,6 +8,8 @@ New Features
 
 * Improve performance while importing multiple regions. [#3321]
 
+* API method to toggle API hints. [#3336]
+
 Cubeviz
 ^^^^^^^
 

docs/plugin_api.rst

@@ -14,4 +14,8 @@ For example:
   plugin.open_in_tray()
   plugin.show('popout')
 
-When running in a notebook, some plugins provide API hints directly in the UI.  To enable these, toggle the ``<>`` button in the top of the plugin.
+When running in a notebook, some plugins provide API hints directly in the UI.  To enable these, toggle the ``[API]`` button on the top bar of the app or call:
+
+.. code-block:: python
+
+  viz.toggle_api_hints()

jdaviz/core/helpers.py

@@ -453,6 +453,20 @@ def show_in_new_tab(self, title=None):  # pragma: no cover
                       DeprecationWarning)
         return self.show(loc="sidecar:tab-after", title=title)
 
+    def toggle_api_hints(self, enabled=None):
+        """
+        Toggle the visibility of API hints in the application.
+
+        Parameters
+        ----------
+        enabled : bool, optional
+            If `True`, show API hints. If `False`, hide API hints.
+            If `None`, toggle the current state.
+        """
+        if enabled is None:
+            enabled = not self.app.state.show_api_hints
+        self.app.state.show_api_hints = enabled
+
     def _handle_display_units(self, data, use_display_units=True):
         if use_display_units:
             if isinstance(data, Spectrum1D):

jdaviz/tests/test_user_api.py

@@ -37,3 +37,13 @@ def test_specviz_data_labels(specviz_helper, spectrum1d):
     assert specviz_helper.data_labels == [label]
     assert specviz_helper.viewers['spectrum-viewer'].data_labels_loaded == [label]
     assert specviz_helper.viewers['spectrum-viewer'].data_labels_visible == [label]
+
+
+def test_toggle_api_hints(specviz_helper):
+    assert specviz_helper.app.state.show_api_hints is False
+    specviz_helper.toggle_api_hints()
+    assert specviz_helper.app.state.show_api_hints is True
+    specviz_helper.toggle_api_hints(True)
+    assert specviz_helper.app.state.show_api_hints is True
+    specviz_helper.toggle_api_hints()
+    assert specviz_helper.app.state.show_api_hints is False