Python console interactive help

[YoannQDQ]

• Fix Shortcut to open pyqgis API from QGIS console/script #36338

Description

Add a shortcut in python editors to open the API

When pressing F1, open the API page matching

• selected text if any OR
• word at the mouse position (if enabled in settings, see below) OR
• word at the text cursor position

Behavior is slighltly different for the Python Console (and editors) and for the others generic QgsCodeEditorPython (e.g Expression Editor).

Generic editors

This PR only improves the already existing "Search in PyQGIS Documentation" action in the context menu to add the F1 shortcut and the word under mouse logic. Besides, if the text hovered matches a Qt class name, the Qt API is opened at the correct page. PyQGIS documentation urls cannot be deduced from the class name only as they also include the module name, so pressing F1 will only search the PyQGIS documentation.

Python console (where the PR truly shines)

Add a widget in the devtools panel to display the API documentation (PyQGIS and Qt)

The buttons at the top of the widget access the home pages of the APIs.
The button at the top right opens the current URL in the system web browser

When pressing F1 while hovering a symbol on the Python Console or Editors tab, the object is evaluated to get its class and module. The relevant API (PyQGIS or Qt) is then opened at the correct page. It works for class names, class, or even objects

Consider the following snippet:

myLayer = iface.activeLayer() 
if isinstance(myLayer, QgsRasterLayer):
  print("It is a QgsRasterLayer")
a = QLabel()

Let's say the active layer is a vector layer. With the text cursor at the following words, pressing F1 will

• myLayer: open the PyQGIS api page for QgsVectorLayer.
• iface: open the PyQGIS api page for QgisInterface.
• QLabel: open the Qt api page for QLabel
• QgsRasterLayer (in the print statement or in the type check): open the Qt api page for QgsRasterLayer

If the symbol is not recognized, open the PyQGIS API home page.

Settings

• Open In: how should the API html page be displayed?
  • Embedded Webview
  • Default system Web browser
• F1 on Hover: whether pressing F1 should trigger the context help for the hovered word or for the word at the textCursor

Demo

[nyalldawson]

Nice work @YoannQDQ !!

which API should be displayed

Is there a compelling reason we'd want to use C++ now? In the last month the PyQGIS docs.have greatly improved, and I'd argue they are at least as good as the C++ ones now...

PyQt doc is often incomplete)

This is the right call for the qt docs 👍

[github-actions]

🪟 Windows builds ready!

Windows builds of this PR are available for testing here. Debug symbols for this build are available here.

(Built from commit d1bdd2b)

[uclaros]

This is great!
I find the hover + F1 functionality a little counter intuitive, though.
I would expect the word at text cursor position to always take precedence.

[YoannQDQ]

Is there a compelling reason we'd want to use C++ now? In the last month the PyQGIS docs.have greatly improved, and I'd argue they are at least as good as the C++ ones now...

Out of habit, I mostly read the C++ API doc myself, but I'm completely willing to letting it go. Should it also be removed from the help menu?

I find the hover + F1 functionality a little counter intuitive, though

I took it from QtCreator, but if it doesn't feel right, we can ditch it. I'd appreciate some more feedback on this.

[github-actions]

🪟 Windows builds

Download Windows builds of this PR for testing.
Debug symbols for this build are available here.
(Built from commit c790356)

🪟 Windows Qt6 builds

Download Windows Qt6 builds of this PR for testing.
(Built from commit c790356)

[uclaros]

I took it from QtCreator, but if it doesn't feel right, we can ditch it. I'd appreciate some more feedback on this.

Just curious, what QtCreator version is this in? On my 13.0.2 the hovered item is ignored, and it makes perfect sense for me as the mouse cursor may be anywhere when navigating with the keyboard!

[YoannQDQ]

It's an ancient version of qt creator that we keep using on a specific project for ungodly reasons... Namely QtCreator 4.11. This behavior has indeed disappeared in later versions.

[YoannQDQ]

@nyalldawson The "search" function of the PyQGIS documentation works with QWebEngineView. Are there any plan to make it available in C++? Maybe integrate it to QgsWebView?

[nyalldawson]

@YoannQDQ

We should just be able to use the QWebEngineView class directly, without any need for a Qgs wrapper class. We'd just need to conditionally use it only in #ifdef HAVE_WEBENGINE blocks

[YoannQDQ]

Thanks for the review! I also added the conditional QWebEngineView include.

[YoannQDQ]

@nyalldawson Would it be possible to merge this now?

[nyalldawson]

@YoannQDQ

Would it be possible to merge this now?

Sorry, was off last week with FOSS4G Oceania ... it's going to take me a bit of time to catch back up on QGIS work now 😆

[qgis-bot]

@YoannQDQ

This pull request has been tagged for the changelog.

• The description will be harvested so please provide a "nearly-ready" text for the final changelog
• If possible, add a nice illustration of the feature. Only the first one in the description will be harvested (GIF accepted as well)
• If you can, it's better to give credits to your sponsor, see below for different formats.

You can edit the description.

Format available for credits

• Funded by NAME
• Funded by URL
• Funded by NAME URL
• Sponsored by NAME
• Sponsored by URL
• Sponsored by NAME URL

Thank you!

[qgis-bot]

@YoannQDQ
This pull request has been tagged as requiring documentation.

A documentation ticket will be opened at https://github.com/qgis/QGIS-Documentation when this PR is merged.

Please update the description (not the comments) with helpful description and screenshot to help the work from documentors.
Also, any commit having [needs-doc] or [Needs Documentation] in will see its message pushed to the issue, so please be as verbose as you can.

Thank you!

[nyalldawson]

@YoannQDQ just a few minor cleanups left 👍

[nyalldawson]

Thanks @YoannQDQ !

[qgis-bot]

@YoannQDQ
A documentation ticket has been opened at qgis/QGIS-Documentation#9384
It is your responsibility to visit this ticket and add as much detail as possible for the documentation team to correctly document this change.
Thank you!