MantidHelpWindow.cpp

Go to the documentation of this file.

// Mantid Repository : https://github.com/mantidproject/mantid
//
// Copyright © 2018 ISIS Rutherford Appleton Laboratory UKRI,
//   NScD Oak Ridge National Laboratory, European Spallation Source,
//   Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS
// SPDX - License - Identifier: GPL - 3.0 +
#include "MantidQtWidgets/Common/MantidHelpWindow.h"
#include "MantidAPI/AlgorithmManager.h"
#include "MantidKernel/ConfigService.h"
#include "MantidKernel/Logger.h"
#include "MantidKernel/RegistrationHelper.h"
#include "MantidQtWidgets/Common/InterfaceManager.h"
#include "MantidQtWidgets/Common/MantidDesktopServices.h"
#include "MantidQtWidgets/Common/pqHelpWindow.h"
#include <Poco/File.h>
#include <Poco/Path.h>
#include <QApplication>
#include <QDir>
#include <QFileInfo>
#include <QHelpEngine>
#include <QLatin1Char>
#include <QLatin1String>
#include <QResource>
#include <QStandardPaths>
#include <QString>
#include <QTemporaryFile>
#include <QTextStream>
#include <QUrl>
#include <QWidget>
#include <boost/lexical_cast.hpp>
#include <memory>
#include <stdexcept>
 
namespace MantidQt::MantidWidgets {
 
using std::string;
using namespace MantidQt::API;
 
REGISTER_HELPWINDOW(MantidHelpWindow)
 
namespace {
Mantid::Kernel::Logger g_log("MantidHelpWindow");
} // namespace
 
// initialise the help window
QPointer<pqHelpWindow> MantidHelpWindow::g_helpWindow;
 
const QString BASE_URL("qthelp://org.mantidproject/doc/");
const QString DEFAULT_URL(BASE_URL + "index.html");
 
const QString WIKI_BASE_URL("https://www.mantidproject.org/");
const QString WIKI_DEFAULT_URL(WIKI_BASE_URL + "MantidPlot");
 
const QString COLLECTION_FILE("MantidProject.qhc");
 
MantidHelpWindow::MantidHelpWindow(const Qt::WindowFlags &flags)
    : MantidHelpInterface(), m_collectionFile(""), m_cacheFile(""), m_firstRun(true) {
  // find the collection and delete the cache file if this is the first run
  if (!helpWindowExists()) {
    this->determineFileLocs();
 
    // see if chache file exists and remove it - shouldn't be necessary, but it
    // is
    if (!m_cacheFile.empty()) {
      if (Poco::File(m_cacheFile).exists()) {
        g_log.debug() << "Removing help cache file \"" << m_cacheFile << "\"\n";
        Poco::File(m_cacheFile).remove();
      } else {
        Poco::Path direcPath = Poco::Path(m_cacheFile).parent(); // drop off the filename
        Poco::File direcFile(direcPath.absolute().toString());
        if (!direcFile.exists()) {
          direcFile.createDirectories();
        }
      }
    }
 
    // create the help engine with the found location
    g_log.debug() << "Loading " << m_collectionFile << "\n";
    auto helpEngine = new QHelpEngine(QString(m_collectionFile.c_str()));
    QObject::connect(helpEngine, SIGNAL(warning(QString)), this, SLOT(warning(QString)));
    g_log.debug() << "Making local cache copy for saving information at " << m_cacheFile << "\n";
 
    if (helpEngine->copyCollectionFile(QString(m_cacheFile.c_str()))) {
      helpEngine->setCollectionFile(QString(m_cacheFile.c_str()));
    } else {
      g_log.warning("Failed to copy collection file");
      g_log.debug(helpEngine->error().toStdString());
    }
    g_log.debug() << "helpengine.setupData() returned " << helpEngine->setupData() << "\n";
 
    // create a new help window
    g_helpWindow = new pqHelpWindow(helpEngine, this, flags);
    g_helpWindow->setWindowTitle(QString("Mantid - Help"));
    g_helpWindow->setWindowIcon(QIcon(":/images/MantidIcon.ico"));
 
    // show the home page on startup
    auto registeredDocs = helpEngine->registeredDocumentations();
    if (registeredDocs.size() > 0) {
      g_helpWindow->showHomePage(registeredDocs[0]);
    }
    g_helpWindow->show();
    g_helpWindow->raise();
  }
}
 
void MantidHelpWindow::showHelp(const QString &url) {
  g_log.debug() << "open help window for \"" << url.toStdString() << "\"\n";
  // bring up the help window if it is showing
  g_helpWindow->show();
  g_helpWindow->raise();
  if (!url.isEmpty()) {
    g_helpWindow->showPage(url);
  }
}
 
void MantidHelpWindow::openWebpage(const QUrl &url) {
  g_log.debug() << "open url \"" << url.toString().toStdString() << "\"\n";
  MantidDesktopServices::openUrl(url);
}
 
void MantidHelpWindow::showPage(const QString &url) { this->showPage(QUrl(url)); }
 
void MantidHelpWindow::showPage(const QUrl &url) {
  if (helpWindowExists()) {
    if (url.isEmpty())
      this->showHelp(DEFAULT_URL);
    else
      this->showHelp(url.toString());
  } else // qt-assistant disabled
  {
    if (url.isEmpty())
      this->openWebpage(WIKI_DEFAULT_URL);
    else
      this->openWebpage(url);
  }
}
 
void MantidHelpWindow::showPage(const string &url) { this->showPage(QUrl(QString(url.c_str()))); }
 
void MantidHelpWindow::showWikiPage(const string &page) {
  if (page.empty())
    this->openWebpage(WIKI_DEFAULT_URL);
  else
    this->openWebpage(WIKI_BASE_URL + page.c_str());
}
 
void MantidHelpWindow::showWikiPage(const QString &page) { this->showWikiPage(page.toStdString()); }
 
void MantidHelpWindow::showAlgorithm(const string &name, const int version) {
  auto versionStr("-v" + boost::lexical_cast<string>(version));
  if (version <= 0) {
    versionStr = ""; // let the redirect do its thing
  }
 
  QString help_url("");
  if (!name.empty()) {
    auto alg = Mantid::API::AlgorithmManager::Instance().createUnmanaged(name);
    help_url = QString::fromStdString(alg->helpURL());
  }
  if (helpWindowExists()) {
    if (help_url.isEmpty()) {
      QString url(BASE_URL);
      url += "algorithms/";
      if (name.empty()) {
        url += "index.html";
      } else {
        url += QString(name.c_str()) + QString(versionStr.c_str()) + ".html";
      }
      this->showHelp(url);
    } else {
      this->showHelp(help_url);
    }
  } else { // qt-assistant disabled
    if (help_url.isEmpty()) {
      if (name.empty()) {
        this->showWikiPage(std::string("Category:Algorithms"));
      } else {
        this->showWikiPage(name);
      }
    } else {
      this->openWebpage(help_url);
    }
  }
}
 
void MantidHelpWindow::showAlgorithm(const QString &name, const int version) {
  this->showAlgorithm(name.toStdString(), version);
}
 
void MantidHelpWindow::showConcept(const string &name) {
  if (helpWindowExists()) {
    QString url(BASE_URL);
    url += "concepts/";
    if (name.empty())
      url += "index.html";
    else
      url += QString(name.c_str()) + ".html";
    this->showHelp(url);
  } else // qt-assistant disabled
  {
    if (name.empty())
      this->showWikiPage(std::string("Category:Concepts"));
    else
      this->showWikiPage(name);
  }
}
 
void MantidHelpWindow::showConcept(const QString &name) { this->showConcept(name.toStdString()); }
 
void MantidHelpWindow::showFitFunction(const std::string &name) {
  if (helpWindowExists()) {
    QString url(BASE_URL);
    url += "fitting/fitfunctions/";
    auto functionUrl = url + QString(name.c_str()) + ".html";
    if (name.empty() || !g_helpWindow->isExistingPage(functionUrl))
      url += "index.html";
    else
      url = functionUrl;
 
    this->showHelp(url);
  } else // qt-assistant disabled
  {
    if (name.empty())
      this->showWikiPage(std::string("Category:Fit_functions"));
    else
      this->showWikiPage(name);
  }
}
 
void MantidHelpWindow::showFitFunction(const QString &name) { this->showFitFunction(name.toStdString()); }
 
void MantidHelpWindow::showCustomInterface(const QString &name, const QString &area, const QString &section) {
  this->showCustomInterface(name.toStdString(), area.toStdString(), section.toStdString());
}
 
void MantidHelpWindow::showCustomInterface(const std::string &name, const std::string &area,
                                           const std::string &section) {
  if (helpWindowExists()) {
    QString url(BASE_URL);
    url += "interfaces/";
    if (!area.empty()) {
      url += QString::fromStdString(area) + "/";
    }
    if (name.empty()) {
      url += "index.html";
    } else {
      url += QString::fromStdString(name) + ".html";
      if (!section.empty()) {
        url += "#" + QString::fromStdString(section);
      }
    }
    this->showHelp(url);
  }
}
 
void MantidHelpWindow::shutdown() {
  // close the window and delete the object
  // Deleting the object ensures the help engine's destructor is called and
  // avoids a segfault when workbench is closed
  g_helpWindow->setAttribute(Qt::WA_DeleteOnClose);
  g_helpWindow->close();
}
 
void MantidHelpWindow::findCollectionFile(std::string &binDir) {
  // this being empty notes the feature being disabled
  m_collectionFile = "";
 
  QDir searchDir(QString::fromStdString(binDir));
 
  // try next to the executable
  QString path = searchDir.absoluteFilePath(COLLECTION_FILE);
  g_log.debug() << "Trying \"" << path.toStdString() << "\"\n";
  if (searchDir.exists(COLLECTION_FILE)) {
    m_collectionFile = path.toStdString();
    return;
  } else {
    g_log.debug() << "QHelp Collection file " << path.toStdString() << " not found\n";
  }
 
  // try where the builds will put it for a single configuration build
  searchDir.cdUp();
  if (searchDir.cd("docs")) {
    searchDir.cd("qthelp");
    path = searchDir.absoluteFilePath(COLLECTION_FILE);
    g_log.debug() << "Trying \"" << path.toStdString() << "\"\n";
    if (searchDir.exists(COLLECTION_FILE)) {
      m_collectionFile = path.toStdString();
      return;
    }
  }
  // try where the builds will put it for a multi-configuration build
  searchDir.cdUp();
  if (searchDir.cd("docs")) {
    searchDir.cd("qthelp");
    path = searchDir.absoluteFilePath(COLLECTION_FILE);
    g_log.debug() << "Trying \"" << path.toStdString() << "\"\n";
    if (searchDir.exists(COLLECTION_FILE)) {
      m_collectionFile = path.toStdString();
      return;
    }
  }
 
  // try in windows/linux install location
  searchDir = QDir(QString::fromStdString(binDir));
  searchDir.cdUp();
  searchDir.cd("share");
  searchDir.cd("doc");
  path = searchDir.absoluteFilePath(COLLECTION_FILE);
  g_log.debug() << "Trying \"" << path.toStdString() << "\"\n";
  if (searchDir.exists(COLLECTION_FILE)) {
    m_collectionFile = path.toStdString();
    return;
  }
 
  // try a special place for mac/osx
  searchDir = QDir(QString::fromStdString(binDir));
  searchDir.cdUp();
  searchDir.cdUp();
  searchDir.cd("share");
  searchDir.cd("doc");
  path = searchDir.absoluteFilePath(COLLECTION_FILE);
  g_log.debug() << "Trying \"" << path.toStdString() << "\"\n";
  if (searchDir.exists(COLLECTION_FILE)) {
    m_collectionFile = path.toStdString();
    return;
  }
 
  // all tries have failed
  g_log.information("Failed to find help system collection file \"" + COLLECTION_FILE.toStdString() + "\"");
}
 
void MantidHelpWindow::determineFileLocs() {
  // determine collection file location
  string binDir = Mantid::Kernel::ConfigService::Instance().getPropertiesDir();
 
  this->findCollectionFile(binDir);
  if (m_collectionFile.empty()) {
    // clear out the other filenames
    m_cacheFile = "";
    return;
  }
  g_log.debug() << "Using collection file \"" << m_collectionFile << "\"\n";
 
  // determine cache file location
  m_cacheFile = COLLECTION_FILE.toStdString();
 
  QString dataLoc = QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + "/data";
 
  if (dataLoc.endsWith("mantidproject")) {
    Poco::Path path(dataLoc.toStdString(), m_cacheFile);
    m_cacheFile = path.absolute().toString();
  } else if (dataLoc.endsWith("MantidPlot")) // understood to end in "Mantid/MantidPlot"
  {
    Poco::Path path(dataLoc.toStdString());
    path = path.parent(); // drop off "MantidPlot"
    path = path.parent(); // drop off "Mantid"
    path = Poco::Path(path, "mantidproject");
    path = Poco::Path(path, m_cacheFile);
    m_cacheFile = path.absolute().toString();
  } else {
    g_log.debug() << "Failed to determine help cache file location\n"; // REMOVE
    Poco::Path path(dataLoc.toStdString(), "mantidproject");
    path = Poco::Path(path, COLLECTION_FILE.toStdString());
    m_cacheFile = path.absolute().toString();
  }
}
 
void MantidHelpWindow::warning(const QString &msg) { g_log.warning(msg.toStdString()); }
 
} // namespace MantidQt::MantidWidgets