Python Help Window Prototype to remove qtassistant

[darshdinger]

Description of work

Summary of work

These enhancements feature refined CMake and Conda configurations alongside innovative implementations in both C++ and Python for a modern, Python-based help window. Collectively, these improvements lay a solid foundation for migrating away from the legacy QtAssistant system toward a more contemporary, flexible approach that leverages web based tech. This transition is designed to resolve longstanding challenges, such as the excessive package size and the absence of JavaScript support.

The primary purpose of this work was to enhance the user documentation experience in Mantid Workbench by:

• Reducing dependency on the bulky QtAssistant system.
• Preparing the system for future integration with QtWebEngine/QtWebView to support modern web features like JavaScript for dynamic content and equation rendering.
• Bridging Python and C++ layers for a seamless help interface that can dynamically switch between local and online documentation sources.

Ref #37248

Further detail of work

CMake and Build Configuration:

• Updated the top-level CMakeLists.txt and associated Conda recipe files to accommodate new build options and dependencies (thanks @peterfpeterson). These changes ensure that necessary packages like PyQtWebEngine are available in the environment, allowing for QtWebView integration.

Help Window Architecture Enhancements:

• Python Integration:

  • Implemented PythonHelpBridge to establish a communication channel between C++ and Python. This bridge initializes the Python interpreter, imports the necessary Python modules, and calls Python functions to display help pages.
  • Developed PythonHelpWindow class which utilizes the bridge to invoke Python functions for displaying various documentation pages (algorithms, concepts, fit functions, and custom interfaces). This paves the way for using QtWebEngine in future iterations by abstracting the method of displaying web content.
  • Integrated logic in the help window presenter and view to decide between loading local documentation and falling back to the online Mantid documentation based on environment variables (MANTID_LOCAL_DOCS_BASE) and file existence.
  • Employed QWebEngineView (as seen in the Python samples and bridging code) to provide a more modern method of rendering documentation. Although the full QtWebEngine integration is prototyped and contextually referenced, the current changes establish the foundational elements necessary for this transition.

• C++ Components:

  • Refactored the MantidHelpWindow to improve how the help system locates and loads the QtHelp collection file (MantidProject.qhc).
  • Enhanced the InterfaceManager's functionality to dynamically manage help window instances. Depending on build configurations (e.g., using cmake .. -DDOCS_QTHELP=OFF), it can intelligently instantiate either a native C++ help window or a Python-based alternative.

To test:

This is suggested things to test. Trying to start the help from other methods is suggested as well.

1. Rather than creating a new mantid-developer conda package, install pyqtwebengine on top of your existing mantid-developer conda environment. You may want to pin the version of pyqtwebengine to whatever version of pyqt you're using so conda doesn't uninstall mantid-developer
2. Re-run cmake with a switch to use the qtwebengine implementation cmake . -DDOCS_QTHELP=off
3. Build mantidworkbench and start it
4. Press F1 or use the "Help"->"Mantid Help" menu item. This should bring up the new help window.
5. Open any algorithm and press the "?" button to bring up the help.
6. Use the menu to open "Interfaces"->"Diffraction"->"Engineering Diffraction" then press the "?" button to bring up the help.

Also try both leaving the help open and starting a different help page and closing the help and starting a different help page.

---

Reviewer

Please comment on the points listed below (full description).
Your comments will be used as part of the gatekeeper process, so please comment clearly on what you have checked during your review. If changes are made to the PR during the review process then your final comment will be the most important for gatekeepers. In this comment you should make it clear why any earlier review is still valid, or confirm that all requested changes have been addressed.

Code Review

• Is the code of an acceptable quality?
• Does the code conform to the coding standards?
• Are the unit tests small and test the class in isolation?
• If there is GUI work does it follow the GUI standards?
• If there are changes in the release notes then do they describe the changes appropriately?
• Do the release notes conform to the release notes guide?

Functional Tests

• Do changes function as described? Add comments below that describe the tests performed?
• Do the changes handle unexpected situations, e.g. bad input?
• Has the relevant (user and developer) documentation been added/updated?

Does everything look good? Mark the review as Approve. A member of @mantidproject/gatekeepers will take care of it.

Gatekeeper

If you need to request changes to a PR then please add a comment and set the review status to "Request changes". This will stop the PR from showing up in the list for other gatekeepers.

[github-actions]

👋 Hi, @darshdinger,

Conflicts have been detected against the base branch. Please rebase your branch against the base branch.