Best way to add general docs and help menu?

[HagaiHargil]

Hi :)

My main use case for magicgui is to replace command line applications with friendlier, GUI-based tools. This is very helpful for my non-coder colleagues, and magicgui has been invaluable on that front. One thing that I "miss" from CLI tools is documentation for the available parameters and more general "help documentation" which explains the use case that this current app is here to solve. In CLI tools these bits of information can usually be invoked with a --help flag which is obviously missing here.

I was wondering whether you think it would be possible to add text box for each parameter of the GUI which appears following a hover "event". This text box may pull its information from the docstring of the main annotated function (moar magik!). If you think it's doable I might try to dip my toes into this magical swamp.

In addition, a more traditional "Help" context menu or button can be optionally activated by adding a "help_button: True" entry to the main magicgui dictionary. This button can again get its information from the main body of the function's docstring.

How does it sound to you? I believe some docstring magic is already happening in order to decipher each type's designated widget.

[tlambert03]

How does it sound to you?

sounds great! it's definitely inline with the goal of making it easy for developers to provide usable GUIs to people (and if it's not clear what all the widgets do, then it's not very useable! 😂)

I believe some docstring magic is already happening in order to decipher each type's designated widget.

we actually don't really use the docstrings much for type or widget inference (that all comes from either the type annotation, the default value, or the parameters to magicgui())... however, you might be interested in the tooltips PR that recently merged! https://github.com/napari/magicgui/pull/100 (not yet released)

That should hopefully satisfy part of the need here... but as you'll notice in that PR, the tooltips are restricted to the first sentence of the parameter docstring. So a full-blown help would also be useful (maybe if help_buton is true, a little ℹ️ could appear somewhere in the widget that pops up the full docstring?)

[tlambert03]

I haven't added tooltips to the online docs yet... so until then, the best examples for tuning its behavior are probably these tests

[HagaiHargil]

Awesome, I missed that issue and the PR completely! I knew that "hover text box" wasn't the right phrase but I couldn't find a better one, thanks for these references.

I wonder why do you parse only the first sentence (up to the first comma or period)? Is there some technical limitation or do you think that it's simply better this way?

I believe that an ℹ️ emoji is great, I'll try taking a deeper look.

[tlambert03]

I wonder why do you parse only the first sentence (up to the first comma or period)? Is there some technical limitation or do you think that it's simply better this way?

It was a somewhat arbitrary decision, and with probably even a little nudging I could be convinced otherwise :). No technical limitations. Was just trying to keep the UI relatively clean... But maybe it was too strong of a choice. A developer can always override the tooltips, as shown in those examples, so maybe we should just use the whole parameter docstring and leave it up to the dev to shorten manually if desired?

[HagaiHargil]

Honestly I can't think of a reason to cut off the tooltip this way a priori :X I'm not sure that a large tooltip text box will affect the cleanliness of the UI too much, because usability is more important than 'cleanliness' IMO, and we're talking about a disappearing tooltip - one that the developer can override quite easily.

[tlambert03]

sounds good, I'm convinced! :) Any interest in submitting a PR to remove these two lines of splits:
https://github.com/napari/magicgui/blob/45e7a15ac85f5e9a12249575c8efff80e0172d34/magicgui/function_gui.py#L30-L31

and then update the tests correspondingly?
(if not, I can take care of it too)

[HagaiHargil]

Sure, I'll do it. Thanks!

[HagaiHargil]

Regarding that ℹ️ widget - I'll need a QIcon widget, at least for the Qt backend. Do you think I should add it in _concrete.py and then import it to and from widgets.py or is there some other preferred way?

[tlambert03]

yeah, that's a good question. It's not immediately clear how this is going to work across different backends. Maybe one idea, since the implementation here likely to be rather backend-dependent, is that we add just one _mgui_provide_help_icon method to magicgui.widgets._protocols.ContainerProtocol... then you can do whatever you want inside the magicgui.backends._qtpy.widgets.Contaniner._mgui_provide_help_icon implementation to create a QIcon and add it to self._layout. Then in magicgui.widgets._bases.ContainerWidget, we would have a method:

def set_help_text(self, text: str = None):
    # if text is `None`, backends should remove the icon.
    self._widget._mgui_provide_help_icon(text)

thoughts?

[HagaiHargil]

I'm still exploring the parameter space here, as I'm not sure that this type of button is considered best practice. Perhaps a "Help -> About" button in the top app menu, that will only be shown if the help button is set to True is a better idea?

[tlambert03]

Perhaps a "Help -> About" button in the top app menu, that will only be shown if the help button is set to True is a better idea?

Sure I like that, however... there is no menu bar at all yet. For that, we'd need to make widgets a QMainWindow and hookup some of the necessary functionality.

Most of what exists here was written with the idea of small composable widgets to be plugged into other things, and less as the whole application itself. Perhaps we need another main_window=True flag or something for widgets that want to be the entire application unto themselves? That would require more tooling to hook it up properly, but would likely be more extensible in the long run.

[tlambert03]

I'm not sure that this type of button is considered best practice.

(I agree with you by the way, this would probably be the kind of thing that was annoying over time)

[HagaiHargil]

I see... I keep forgetting that magicgui's prime use case is napari 😆

I guess it seems like a pretty big chunk of work needed for a very small benefit, and I'm not sure I can do it myself. Perhaps the tooltips are good enough after all.