Merge pull request #30787 from mantidproject/help_url_error

Improved interface help interaction (ornlnext)

Framework/PythonInterface/plugins/algorithms/AlignComponents.py

@@ -512,22 +512,22 @@ class AlignComponents(PythonAlgorithm):
 
         .. math::
 
-            \sum_i^{N_d}\sum_j^{N_p} (1 - m_{i,j}) \frac{|d_{i,j} - d_j^*|}{d_j^*}
+            \\sum_i^{N_d}\\sum_j^{N_p} (1 - m_{i,j}) \\frac{|d_{i,j} - d_j^*|}{d_j^*}
 
         where :math:`N_d` is the number of detectors in the bank, :math:`N_p` is the number of reference peaks, and
         :math:`m_{i,j}` is the mask for peak :math:`j` and detector :math:`i`. The mask evaluates to 1 if the
         detector is defective or the peak is missing in the detector, otherwise the mask evaluates to zero.
 
-        There's an implicit one-to-correspondence between array index of `difc` and workspace index of `wks_name`,
-        that is, between row index of the input TOFS table and workspace index of `wks_name`.
+        There's an implicit one-to-correspondence between array index of ``difc`` and workspace index of ``wks_name``,
+        that is, between row index of the input TOFS table and workspace index of ``wks_name``.
 
         @param x_0 :: list of length 3 (new XYZ coordinates of the component) or length 6 (XYZ and rotation coords)
         @param wks_name :: name of a workspace with an embedded instrument. The instrument will be adjusted according to
-            the new coordinates `x_0` for instrument component `component`. It's pixel spectra will contain the new DIFC
+            the new coordinates ``x_0`` for instrument component ``component``. It's pixel spectra will contain the new DIFC
         @param component :: name of the instrument component to be optimized
-        @param firstIndex :: workspace index of first index of `difc` array to be considered when comparing old
+        @param firstIndex :: workspace index of first index of ``difc`` array to be considered when comparing old
             and new DIFC values. When fitting the source or sample, this is the first spectrum index.
-        @param lastIndex ::  workspace index of last index of `difc` array to be considered when comparing old
+        @param lastIndex ::  workspace index of last index of ``difc`` array to be considered when comparing old
             and new DIFC values. When fitting the source or sample, this is the last row number of the input
             TOFS table.
 
@@ -557,7 +557,7 @@ class AlignComponents(PythonAlgorithm):
 
         @param component :: reference to a detector component object
 
-        @returns detector ID (`int`) of the first detector in the component
+        @returns detector ID (``int``) of the first detector in the component
         """
         if component.type() == 'DetectorComponent' or component.type() == 'GridDetectorPixel':
             return component.getID()

qt/python/mantidqt/_common.sip

@@ -328,7 +328,7 @@ public:
   void showAlgorithmHelp(const QString &name, const int version=-1);
   void showConceptHelp(const QString &name);
   void showFitFunctionHelp(const QString &name=QString());
-  void showCustomInterfaceHelp(const QString &name);
+  void showCustomInterfaceHelp(const QString &name, const QString &area=QString(), const QString &section=QString());
   void showWebPage(const QString &url);
   void closeHelpWindow();
 };

qt/python/mantidqt/gui_helper.py

@@ -9,6 +9,14 @@ from qtpy import QtCore, QtGui
 import matplotlib
 import sys
 import os
+try:
+    from mantid import __version__ as __mtd_version
+    from mantid import _bindir as __mtd_bin_dir
+    # convert to major.minor
+    __mtd_version = '.'.join(__mtd_version.split(".")[:2])
+except ImportError:  # mantid not found
+    __mtd_version = ''
+    __mtd_bin_dir=''
 
 
 def set_matplotlib_backend():
@@ -25,10 +33,10 @@ def set_matplotlib_backend():
             backend = 'Qt5Agg'
     else:
         from qtpy import PYQT4, PYQT5  # noqa
-        if PYQT4:
-            backend = 'Qt4Agg'
-        elif PYQT5:
+        if PYQT5:
             backend = 'Qt5Agg'
+        elif PYQT4:
+            backend = 'Qt4Agg'
         else:
             raise RuntimeError('Do not know which matplotlib backend to set')
         matplotlib.use(backend)
@@ -50,31 +58,55 @@ def get_qapplication():
         return QApplication(sys.argv), False
 
 
-def show_interface_help(mantidplot_name, assistant_process, collection_file, qt_url, external_url):
+def __to_external_url(interface_name: str, section: str, external_url: str) -> QtCore.QUrl:
+    if not external_url:
+        template = 'http://docs.mantidproject.org/nightly/interfaces/{}/{}.html'
+        external_url = template.format(section, interface_name)
+
+    return QtCore.QUrl(external_url)
+
+
+def __to_qthelp_url(interface_name: str, section: str, qt_url: str) -> str:
+    if qt_url:
+        return qt_url
+    else:
+        template = 'qthelp://org.sphinx.mantidproject.{}/doc/interfaces/{}/{}.html'
+        return template.format(__mtd_version, section, interface_name)
+
+
+def __get_collection_file(collection_file: str) -> str:
+    if not collection_file:
+        if not __mtd_bin_dir:
+            return 'HELP COLLECTION FILE NOT FOUND'
+        else:
+            collection_file = os.path.join(__mtd_bin_dir, '../docs/qthelp/MantidProject.qhc')
+
+    return os.path.abspath(collection_file)
+
+
+def show_interface_help(mantidplot_name, assistant_process, area: str='',
+                        collection_file: str='',
+                        qt_url: str='', external_url: str=""):
     ''' Shows the help page for a custom interface
     @param mantidplot_name: used by showCustomInterfaceHelp
     @param assistant_process: needs to be started/closed from outside (see example below)
-    @param collection_file: qth file containing the help in format used by qtassistant
-    @param qt_url: location of the help in the qth file
-    @param external_url: location of external page to be displayed in the default browser
+    @param collection_file: qth file containing the help in format used by qtassistant. The default is
+    ``mantid._bindir + '../docs/qthelp/MantidProject.qhc'``
+    @param qt_url: location of the help in the qth file. The default value is
+    ``qthelp://org.sphinx.mantidproject.{mtdversion}/doc/interfaces/{mantidplot_name}.html``.
+    @param external_url: location of external page to be displayed in the default browser. The default value is
+    ``http://docs.mantidproject.org/nightly/interfaces/framework/{mantidplot_name}.html``
 
-    Example:
+    Example using defaults:
 
     #in the __init__ function of the GUI add:
     self.assistant_process = QtCore.QProcess(self)
     self.mantidplot_name='DGS Planner'
-    self.collection_file = os.path.join(mantid._bindir, '../docs/qthelp/MantidProject.qhc')
-    version = ".".join(mantid.__version__.split(".")[:2])
-    self.qt_url = 'qthelp://org.sphinx.mantidproject.' + version + '/doc/interfaces/DGS Planner.html'
-    self.external_url = 'http://docs.mantidproject.org/nightly/interfaces/DGS Planner.html'
 
     #add a help function in the GUI
     def help(self):
        show_interface_help(self.mantidplot_name,
-                           self.assistant_process,
-                           self.collection_file,
-                           self.qt_url,
-                           self.external_url)
+                           self.assistant_process)
 
     #make sure you close the qtassistant when the GUI is closed
     def closeEvent(self, event):
@@ -83,24 +115,40 @@ def show_interface_help(mantidplot_name, assistant_process, collection_file, qt_
         event.accept()
     '''
     try:
+        # try using built-in help in mantid
         import mantidqt
-        mantidqt.interfacemanager.InterfaceManager().showCustomInterfaceHelp(mantidplot_name)
+        mantidqt.interfacemanager.InterfaceManager().showCustomInterfaceHelp(mantidplot_name, area)
     except: #(ImportError, ModuleNotFoundError) raises the wrong type of error
+        # built-in help failed, try external qtassistant then give up and launch a browser
+
+        # cleanup previous version
         assistant_process.close()
         assistant_process.waitForFinished()
+
+        # where to expect qtassistant
         helpapp = QtCore.QLibraryInfo.location(QtCore.QLibraryInfo.BinariesPath) + QtCore.QDir.separator()
         helpapp += 'assistant'
-        args = ['-enableRemoteControl', '-collectionFile', collection_file, '-showUrl', qt_url]
+
+        collection_file = __get_collection_file(collection_file)
         if os.path.isfile(helpapp) and os.path.isfile(collection_file):
+            # try to find the collection file and launch qtassistant
+            args = ['-enableRemoteControl',
+                    '-collectionFile', collection_file,
+                    '-showUrl', __to_qthelp_url(mantidplot_name, area, qt_url)]
+
             assistant_process.close()
             assistant_process.waitForFinished()
             assistant_process.start(helpapp, args)
         else:
+            # give up and upen a URL in default browser
             openUrl=QtGui.QDesktopServices.openUrl
             sysenv=QtCore.QProcessEnvironment.systemEnvironment()
             ldp=sysenv.value('LD_PRELOAD')
             if ldp:
                 del os.environ['LD_PRELOAD']
-            openUrl(QtCore.QUrl(external_url))
+
+            # create a url to the help in the default location
+            openUrl(__to_external_url(mantidplot_name, area, external_url))
+
             if ldp:
                 os.environ['LD_PRELOAD']=ldp

qt/scientific_interfaces/Direct/ALFCustomInstrumentView.cpp

@@ -22,7 +22,7 @@ ALFCustomInstrumentView::ALFCustomInstrumentView(const std::string &instrument,
       m_extractSingleTubeObservable(nullptr), m_averageTubeObservable(nullptr),
       m_extractAction(nullptr), m_averageAction(nullptr),
       m_analysisPane(nullptr) {
-  m_helpPage = "ALF View";
+  m_helpPage = "direct/ALF View";
 }
 
 void ALFCustomInstrumentView::setUpInstrument(
@@ -97,4 +97,4 @@ void ALFCustomInstrumentView::addSpectrum(const std::string &wsName) {
 }
 
 } // namespace CustomInterfaces
-} // namespace MantidQt
\ No newline at end of file
+} // namespace MantidQt

qt/scientific_interfaces/EnggDiffraction/EnggDiffractionViewQtGUI.cpp

@@ -1101,7 +1101,7 @@ void EnggDiffractionViewQtGUI::closeEvent(QCloseEvent *event) {
 
 void EnggDiffractionViewQtGUI::openHelpWin() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("Engineering Diffraction"));
+      nullptr, QString("Engineering Diffraction"), QString("diffraction"));
 }
 
 void EnggDiffractionViewQtGUI::updateTabsInstrument(

qt/scientific_interfaces/General/MantidEV.cpp

@@ -507,7 +507,7 @@ void MantidEV::setDefaultState_slot() {
  */
 void MantidEV::help_slot() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("SCD Event Data Reduction"));
+      nullptr, QString("SCD Event Data Reduction"), QString("diffraction"));
 }
 
 /**

qt/scientific_interfaces/General/SampleTransmission.cpp

@@ -55,7 +55,7 @@ void SampleTransmission::initLayout() {
  */
 void SampleTransmission::showHelp() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("Sample Transmission Calculator"));
+      nullptr, QString("Sample Transmission Calculator"), QString("general"));
 }
 
 /**

qt/scientific_interfaces/ISISReflectometry/GUI/MainWindow/MainWindowPresenter.cpp

@@ -306,8 +306,8 @@ void MainWindowPresenter::initNewBatch(IBatchPresenter *batchPresenter,
 }
 
 void MainWindowPresenter::showHelp() {
-  MantidQt::API::HelpWindow::showCustomInterface(nullptr,
-                                                 QString("ISIS Reflectometry"));
+  MantidQt::API::HelpWindow::showCustomInterface(
+      nullptr, std::string("ISIS Reflectometry"), std::string("reflectometry"));
 }
 
 void MainWindowPresenter::notifySaveBatchRequested(int tabIndex) {

qt/scientific_interfaces/Indirect/IndirectInterface.cpp

@@ -25,7 +25,8 @@ IndirectInterface::IndirectInterface(QWidget *parent)
 
 void IndirectInterface::help() {
   HelpWindow::showCustomInterface(nullptr,
-                                  QString::fromStdString(documentationPage()));
+                                  QString::fromStdString(documentationPage()),
+                                  QString("indirect"));
 }
 
 void IndirectInterface::settings() {

qt/scientific_interfaces/Indirect/IndirectSettingsView.cpp

@@ -31,8 +31,8 @@ void IndirectSettingsView::emitApplyClicked() { emit applyClicked(); }
 void IndirectSettingsView::emitCancelClicked() { emit cancelClicked(); }
 
 void IndirectSettingsView::openHelp() {
-  MantidQt::API::HelpWindow::showCustomInterface(nullptr,
-                                                 QString("Indirect Settings"));
+  MantidQt::API::HelpWindow::showCustomInterface(
+      nullptr, QString("Indirect Settings"), QString("indirect"));
 }
 
 void IndirectSettingsView::setSelectedFacility(QString const &text) {

qt/scientific_interfaces/Muon/ALCBaselineModellingView.cpp

@@ -226,7 +226,8 @@ void ALCBaselineModellingView::setSelectorValues(
 }
 
 void ALCBaselineModellingView::help() {
-  MantidQt::API::HelpWindow::showCustomInterface(nullptr, QString("Muon ALC"));
+  MantidQt::API::HelpWindow::showCustomInterface(nullptr, QString("Muon ALC"),
+                                                 QString("muon"));
 }
 
 void ALCBaselineModellingView::emitFitRequested() { emit fitRequested(); }

qt/scientific_interfaces/Muon/ALCDataLoadingView.cpp

@@ -316,7 +316,8 @@ void ALCDataLoadingView::setTimeRange(double tMin, double tMax) {
 }
 
 void ALCDataLoadingView::help() {
-  MantidQt::API::HelpWindow::showCustomInterface(nullptr, QString("Muon ALC"));
+  MantidQt::API::HelpWindow::showCustomInterface(nullptr, QString("Muon ALC"),
+                                                 QString("muon"));
 }
 
 void ALCDataLoadingView::disableAll() {

qt/scientific_interfaces/Muon/ALCPeakFittingView.cpp

@@ -124,7 +124,8 @@ void ALCPeakFittingView::setPeakPicker(const IPeakFunction_const_sptr &peak) {
 }
 
 void ALCPeakFittingView::help() {
-  MantidQt::API::HelpWindow::showCustomInterface(nullptr, QString("Muon ALC"));
+  MantidQt::API::HelpWindow::showCustomInterface(nullptr, QString("Muon ALC"),
+                                                 QString("muon"));
 }
 
 void ALCPeakFittingView::displayError(const QString &message) {

qt/scientific_interfaces/Muon/MuonAnalysis.cpp

@@ -385,8 +385,8 @@ void MuonAnalysis::setChosenGroupAndPeriods(const QString &wsName) {
  * Muon Analysis help (slot)
  */
 void MuonAnalysis::muonAnalysisHelpClicked() {
-  MantidQt::API::HelpWindow::showCustomInterface(nullptr,
-                                                 QString("Muon Analysis"));
+  MantidQt::API::HelpWindow::showCustomInterface(
+      nullptr, QString("Muon Analysis"), QString("muon"));
 }
 
 /**
@@ -394,7 +394,8 @@ void MuonAnalysis::muonAnalysisHelpClicked() {
  */
 void MuonAnalysis::muonAnalysisHelpGroupingClicked() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("Muon Analysis"), QString("grouping-options"));
+      nullptr, QString("Muon Analysis"), QString("muon"),
+      QString("grouping-options"));
 }
 
 /**

qt/scientific_interfaces/Muon/MuonAnalysisFitDataTab.cpp

@@ -37,7 +37,8 @@ void MuonAnalysisFitDataTab::init() {
  */
 void MuonAnalysisFitDataTab::muonAnalysisHelpDataAnalysisClicked() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("Muon Analysis"), QString("data-analysis"));
+      nullptr, QString("Muon Analysis"), QString("muon"),
+      QString("data-analysis"));
 }
 
 /**

qt/scientific_interfaces/Muon/MuonAnalysisOptionTab.cpp

@@ -151,7 +151,7 @@ void MuonAnalysisOptionTab::initLayout() {
  */
 void MuonAnalysisOptionTab::muonAnalysisHelpSettingsClicked() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("Muon Analysis"), QString("settings"));
+      nullptr, QString("Muon Analysis"), QString(""), QString("settings"));
 }
 
 /*
@@ -159,7 +159,7 @@ void MuonAnalysisOptionTab::muonAnalysisHelpSettingsClicked() {
  */
 void MuonAnalysisOptionTab::rebinHelpClicked() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("Muon Analysis"), QString("data-binning"));
+      nullptr, QString("Muon Analysis"), QString(""), QString("data-binning"));
 }
 
 /**

qt/scientific_interfaces/Muon/MuonAnalysisResultTableTab.cpp

@@ -102,7 +102,7 @@ MuonAnalysisResultTableTab::MuonAnalysisResultTableTab(Ui::MuonAnalysis &uiForm)
  */
 void MuonAnalysisResultTableTab::helpResultsClicked() {
   MantidQt::API::HelpWindow::showCustomInterface(
-      nullptr, QString("Muon Analysis"), QString("results-table"));
+      nullptr, QString("Muon Analysis"), QString(""), QString("results-table"));
 }
 
 /**

qt/widgets/common/inc/MantidQtWidgets/Common/HelpWindow.h

@@ -33,10 +33,12 @@ public:
   static void showFitFunction(QWidget *parent,
                               const std::string &name = std::string());
   static void showCustomInterface(QWidget *parent, const QString &name,
+                                  const QString &area = QString(),
                                   const QString &section = QString());
   static void showCustomInterface(QWidget *parent,
                                   const std::string &name = std::string(),
+                                  const std::string &area = std::string(),
                                   const std::string &section = std::string());
 };
 } // namespace API
-} // namespace MantidQt
\ No newline at end of file
+} // namespace MantidQt

qt/widgets/common/inc/MantidQtWidgets/Common/InterfaceManager.h

@@ -100,8 +100,14 @@ public:
   /// @param name of fit function to show help for
   void showFitFunctionHelp(const QString &name = QString());
 
-  /// @param name of interface to show help for
-  void showCustomInterfaceHelp(const QString &name);
+  /**
+   * @param name of interface to show help for
+   * @param area - folder for documentation in the interfaces directory
+   * @param section - section in the html document
+   **/
+  void showCustomInterfaceHelp(const QString &name,
+                               const QString &area = QString(),
+                               const QString &section = QString());
 
   /// @param url of web page to open in browser
   void showWebPage(const QString &url);