Fix problems with the built in help system

ejeschke / ginga

The Ginga astronomical FITS file viewer

BSD 3-Clause "New" or "Revised" License

120 stars 77 forks source link

Fix problems with the built in help system #1084

Closed ejeschke closed 4 months ago

ejeschke commented 6 months ago

This fixes several problems with the built in help system:

The WBrowser plugin is often unable to intialize correctly because it requires a QWebEngineView widget which is often not installed (for example it is offered separately in conda)
Even when the widget is installed, it often can fail to start if OpenGL libraries are not configured correctly (often the case for conda on Linux, for example)
The RTD web site often fails to access certain items, giving a HTTP 403 (Forbidden) error, particularly with trying to fetch the list if versions (ginga.doc.download_doc._find_rtd_version())
The HTML ZIP download (ginga.doc.download_doc. _download_rtd_zip()) sometimes fails as well

Solutions in this PR:

WBrowser plugin is deprecated
For plugin help, the reference viewer will pop up a dialog to ask the user whether they want to view the documentation in an external browser from the RTD link, or view the (local) plugin docstring in a text widget

ejeschke commented 6 months ago

@pllim, I've had a number of problems with the built in help system. This is meant to address them.

When you have time, can you test this with stginga in your environment?

pllim commented 6 months ago

@ejeschke , is there a deadline? I am not sure if I can get to this next week.

ejeschke commented 6 months ago

No deadline. Release 5.0 is way overdue, and now it is looking like late Jan or early Feb.

ejeschke commented 6 months ago

Another possibility, @pllim, is to deprecate the WBrowser plugin completely. We could skip trying to download a zip of HTML (which doesn't seem to work for me anymore) and either show the online documentation in an external browser, or docstrings in a text widget if offline, or the user prefers.

pllim commented 6 months ago

I never used WBrowser myself except to play YouTube in a live demo so I am okay with replacing it with something else.

ejeschke commented 6 months ago

I never used WBrowser myself except to play YouTube in a live demo so I am okay with replacing it with something else.

Ok, sounds good. I feel like the browser widget in Qt (and Gtk) is getting more and more complicated and difficult to support. I read that the Qt browser widget is built on Chrome (!) so it is a pretty complex piece of software to embed.

ejeschke commented 6 months ago

I'll rework this to just deprecate the WBrowser, so hold off reviewing for now...

pllim commented 6 months ago

I am a bit sad because I used to taunt Tom Robitaille saying that glue cannot play YouTube like Ginga. 😆

ejeschke commented 6 months ago

We could replace it with Tetris or Pong...

pllim commented 6 months ago

A kid already broke Tetris. What about Doom? 😸

ejeschke commented 6 months ago

I dunno, maybe a space-based game might be best. There are lots to choose from. Asteroid?

pllim commented 6 months ago

Oh, that is good idea. Or Space Invaders. 🤣

ejeschke commented 6 months ago

Ok, @pllim, when you have a few minutes to try with stginga, please give it a whirl.

ejeschke commented 5 months ago

Rebased

ejeschke commented 5 months ago

@pllim, ok, good point. Let me rework this slightly to make it backward compatible for the help button API.

ejeschke commented 5 months ago

@pllim, I have updated the PR so that the behavior for stginga is the same as if the WBrowser was not installed (because it is actually removed in this PR). I tested with BackgroundSub and it now pops up a text window with the docstring in RST. Can you give a quick test to confirm?

To get the behavior of the PR, where it asks the user whether they want the online help rendered in an external browser or the docstring in a text window, I will submit a PR for stginga.

ejeschke commented 5 months ago

Rebased

ejeschke commented 4 months ago

Thanks, @pllim!