Port model help code to c++

nyalldawson · nyalldawson · commit e7f13f5bd83b · 2017-06-24T07:36:07.000+10:00
diff --git a/python/core/processing/qgsprocessingmodelalgorithm.sip b/python/core/processing/qgsprocessingmodelalgorithm.sip
@@ -566,6 +566,10 @@ Copies are protected to avoid slicing
 
     virtual QString svgIconPath() const;
 
+    virtual QString shortHelpString() const;
+
+    virtual QString helpUrl() const;
+
 
     virtual bool canExecute( QString *errorMessage /Out/ = 0 ) const;
 
@@ -767,6 +771,22 @@ Copies are protected to avoid slicing
  :rtype: bool
 %End
 
+    QVariantMap &helpContent();
+%Docstring
+ Returns the model's help contents (a free-form map of values describing the algorithm's
+ use and metadata).
+.. seealso:: setHelpContent()
+ :rtype: QVariantMap
+%End
+
+
+    void setHelpContent( const QVariantMap &contents );
+%Docstring
+ Sets the model's help ``contents`` (a free-form map of values describing the algorithm's
+ use and metadata).
+.. seealso:: helpContent()
+%End
+
   protected:
 
      virtual QVariantMap processAlgorithm( const QVariantMap &parameters,
diff --git a/python/core/processing/qgsprocessingutils.sip b/python/core/processing/qgsprocessingutils.sip
@@ -151,6 +151,13 @@ class QgsProcessingUtils
  :rtype: str
 %End
 
+    static QString formatHelpMapAsHtml( const QVariantMap &map, const QgsProcessingAlgorithm *algorithm );
+%Docstring
+ Returns a HTML formatted version of the help text encoded in a variant ``map`` for
+ a specified ``algorithm``.
+ :rtype: str
+%End
+
 };
 
 
diff --git a/python/plugins/processing/gui/HelpEditionDialog.py b/python/plugins/processing/gui/HelpEditionDialog.py
@@ -56,7 +56,7 @@ def __init__(self, alg):
         self.alg = alg
         self.descriptions = {}
         if isinstance(self.alg, ModelerAlgorithm):
-            self.descriptions = self.alg.helpContent
+            self.descriptions = self.alg.helpContent()
         else:
             if self.alg.descriptionFile is not None:
                 helpfile = alg.descriptionFile + '.help'
diff --git a/python/plugins/processing/modeler/ModelerAlgorithm.py b/python/plugins/processing/modeler/ModelerAlgorithm.py
@@ -180,7 +180,6 @@ def __init__(self):
         super().__init__()
 
         self.descriptionFile = None
-        self.helpContent = {}
 
         # Geoalgorithms in this model. A dict of Algorithm objects, with names as keys
         self.algs = {}
@@ -235,17 +234,6 @@ def asPythonCommand(self, parameters, context):
         else:
             return None
 
-    def helpUrl(self):
-        try:
-            return getHtmlFromDescriptionsDict(self, self.helpContent)
-        except:
-            return None
-
-    def shortHelpString(self):
-        if 'ALG_DESC' in self.helpContent:
-            return str(self.helpContent['ALG_DESC'])
-        return None
-
     def toPython(self):
         s = ['##%s=name' % self.name()]
         for param in list(self.parameterComponents().values()):
diff --git a/python/plugins/processing/modeler/ModelerDialog.py b/python/plugins/processing/modeler/ModelerDialog.py
@@ -279,7 +279,7 @@ def editHelp(self):
         dlg = HelpEditionDialog(alg)
         dlg.exec_()
         if dlg.descriptions:
-            self.model.helpContent = dlg.descriptions
+            self.model.setHelpContent(dlg.descriptions)
             self.hasChanged = True
 
     def runModel(self):
diff --git a/src/core/processing/qgsprocessingmodelalgorithm.cpp b/src/core/processing/qgsprocessingmodelalgorithm.cpp
@@ -18,6 +18,7 @@
 #include "qgsprocessingmodelalgorithm.h"
 #include "qgsprocessingregistry.h"
 #include "qgsprocessingfeedback.h"
+#include "qgsprocessingutils.h"
 #include "qgsxmlutils.h"
 #include "qgsexception.h"
 #include <QFile>
@@ -292,6 +293,18 @@ QString QgsProcessingModelAlgorithm::svgIconPath() const
   return QgsApplication::iconPath( QStringLiteral( "processingModel.svg" ) );
 }
 
+QString QgsProcessingModelAlgorithm::shortHelpString() const
+{
+  if ( mHelpContent.contains( QStringLiteral( "ALG_DESC" ) ) )
+    return mHelpContent.value( QStringLiteral( "ALG_DESC" ) ).toString();
+  return QString();
+}
+
+QString QgsProcessingModelAlgorithm::helpUrl() const
+{
+  return QgsProcessingUtils::formatHelpMapAsHtml( mHelpContent, this );
+}
+
 QVariantMap QgsProcessingModelAlgorithm::parametersForChildAlgorithm( const ChildAlgorithm &child, const QVariantMap &modelParameters, const QMap< QString, QVariantMap > &results ) const
 {
   QVariantMap childParams;
@@ -468,6 +481,16 @@ QVariantMap QgsProcessingModelAlgorithm::processAlgorithm( const QVariantMap &pa
   return finalResults;
 }
 
+QVariantMap QgsProcessingModelAlgorithm::helpContent() const
+{
+  return mHelpContent;
+}
+
+void QgsProcessingModelAlgorithm::setHelpContent( const QVariantMap &helpContent )
+{
+  mHelpContent = helpContent;
+}
+
 void QgsProcessingModelAlgorithm::setName( const QString &name )
 {
   mModelName = name;
@@ -559,6 +582,7 @@ QVariant QgsProcessingModelAlgorithm::toVariant() const
   QVariantMap map;
   map.insert( QStringLiteral( "model_name" ), mModelName );
   map.insert( QStringLiteral( "model_group" ), mModelGroup );
+  map.insert( QStringLiteral( "help" ), mHelpContent );
 
   QVariantMap childMap;
   QMap< QString, ChildAlgorithm >::const_iterator childIt = mChildAlgorithms.constBegin();
@@ -592,6 +616,7 @@ bool QgsProcessingModelAlgorithm::loadVariant( const QVariant &model )
 
   mModelName = map.value( QStringLiteral( "model_name" ) ).toString();
   mModelGroup = map.value( QStringLiteral( "model_group" ) ).toString();
+  mHelpContent = map.value( QStringLiteral( "help" ) ).toMap();
 
   mChildAlgorithms.clear();
   QVariantMap childMap = map.value( QStringLiteral( "children" ) ).toMap();
diff --git a/src/core/processing/qgsprocessingmodelalgorithm.h b/src/core/processing/qgsprocessingmodelalgorithm.h
@@ -569,6 +569,8 @@ class CORE_EXPORT QgsProcessingModelAlgorithm : public QgsProcessingAlgorithm
     QString group() const override;
     QIcon icon() const override;
     QString svgIconPath() const override;
+    QString shortHelpString() const override;
+    QString helpUrl() const override;
 
     bool canExecute( QString *errorMessage SIP_OUT = nullptr ) const override;
 
@@ -757,6 +759,27 @@ class CORE_EXPORT QgsProcessingModelAlgorithm : public QgsProcessingAlgorithm
      */
     bool fromFile( const QString &path );
 
+    /**
+     * Returns the model's help contents (a free-form map of values describing the algorithm's
+     * use and metadata).
+     * \see setHelpContent()
+     */
+    QVariantMap &helpContent() { return mHelpContent; }
+
+    /**
+     * Returns the model's help contents (a free-form map of values describing the algorithm's
+     * use and metadata).
+     * \see setHelpContent()
+     */
+    SIP_SKIP QVariantMap helpContent() const;
+
+    /**
+     * Sets the model's help \a contents (a free-form map of values describing the algorithm's
+     * use and metadata).
+     * \see helpContent()
+     */
+    void setHelpContent( const QVariantMap &contents );
+
   protected:
 
     QVariantMap processAlgorithm( const QVariantMap &parameters,
@@ -772,6 +795,8 @@ class CORE_EXPORT QgsProcessingModelAlgorithm : public QgsProcessingAlgorithm
     //! Map of parameter name to model parameter component
     QMap< QString, ModelParameter > mParameterComponents;
 
+    QVariantMap mHelpContent;
+
     void dependsOnChildAlgorithmsRecursive( const QString &childId, QSet<QString> &depends ) const;
     void dependentChildAlgorithmsRecursive( const QString &childId, QSet<QString> &depends ) const;
 
diff --git a/src/core/processing/qgsprocessingutils.cpp b/src/core/processing/qgsprocessingutils.cpp
@@ -24,6 +24,7 @@
 #include "qgsvectorfilewriter.h"
 #include "qgsmemoryproviderutils.h"
 #include "qgsprocessingparameters.h"
+#include "qgsprocessingalgorithm.h"
 
 QList<QgsRasterLayer *> QgsProcessingUtils::compatibleRasterLayers( QgsProject *project, bool sort )
 {
@@ -428,6 +429,38 @@ QString QgsProcessingUtils::generateTempFilename( const QString &basename )
   return path + '/' + basename;
 }
 
+QString QgsProcessingUtils::formatHelpMapAsHtml( const QVariantMap &map, const QgsProcessingAlgorithm *algorithm )
+{
+  auto getText = [map]( const QString & key )->QString
+  {
+    if ( map.contains( key ) )
+      return map.value( key ).toString();
+    return QString();
+  };
+
+  QString s = QObject::tr( "<html><body><h2>Algorithm description</h2>\n " );
+  s += QStringLiteral( "<p>" ) + getText( QStringLiteral( "ALG_DESC" ) ) + QStringLiteral( "</p>\n" );
+  s +=  QObject::tr( "<h2>Input parameters</h2>\n" );
+
+  Q_FOREACH ( const QgsProcessingParameterDefinition *def, algorithm->parameterDefinitions() )
+  {
+    s += QStringLiteral( "<h3>" ) + def->description() + QStringLiteral( "</h3>\n" );
+    s += QStringLiteral( "<p>" ) + getText( def->name() ) + QStringLiteral( "</p>\n" );
+  }
+  s += QObject::tr( "<h2>Outputs</h2>\n" );
+  Q_FOREACH ( const QgsProcessingOutputDefinition *def, algorithm->outputDefinitions() )
+  {
+    s += QStringLiteral( "<h3>" ) + def->description() + QStringLiteral( "</h3>\n" );
+    s += QStringLiteral( "<p>" ) + getText( def->name() ) + QStringLiteral( "</p>\n" );
+  }
+  s += "<br>";
+  s += QObject::tr( "<p align=\"right\">Algorithm author: %1</p>" ).arg( getText( QStringLiteral( "ALG_CREATOR" ) ) );
+  s += QObject::tr( "<p align=\"right\">Help author: %1</p>" ).arg( getText( QStringLiteral( "ALG_HELP_CREATOR" ) ) );
+  s += QObject::tr( "<p align=\"right\">Algorithm version: %1</p>" ).arg( getText( QStringLiteral( "ALG_VERSION" ) ) );
+  s += QStringLiteral( "</body></html>" );
+  return s;
+}
+
 
 //
 // QgsProcessingFeatureSource
diff --git a/src/core/processing/qgsprocessingutils.h b/src/core/processing/qgsprocessingutils.h
@@ -183,6 +183,12 @@ class CORE_EXPORT QgsProcessingUtils
      */
     static QString generateTempFilename( const QString &basename );
 
+    /**
+     * Returns a HTML formatted version of the help text encoded in a variant \a map for
+     * a specified \a algorithm.
+     */
+    static QString formatHelpMapAsHtml( const QVariantMap &map, const QgsProcessingAlgorithm *algorithm );
+
   private:
 
     static bool canUseLayer( const QgsRasterLayer *layer );
diff --git a/tests/src/core/testqgsprocessing.cpp b/tests/src/core/testqgsprocessing.cpp
@@ -3732,6 +3732,8 @@ void TestQgsProcessing::modelerAlgorithm()
 
   // to/from XML
   QgsProcessingModelAlgorithm alg5( "test", "testGroup" );
+  alg5.helpContent().insert( "author", "me" );
+  alg5.helpContent().insert( "usage", "run" );
   QgsProcessingModelAlgorithm::ChildAlgorithm alg5c1;
   alg5c1.setChildId( "cx1" );
   alg5c1.setAlgorithmId( "buffer" );
@@ -3772,6 +3774,7 @@ void TestQgsProcessing::modelerAlgorithm()
   QVERIFY( alg6.loadVariant( QgsXmlUtils::readVariant( doc.firstChildElement() ) ) );
   QCOMPARE( alg6.name(), QStringLiteral( "test" ) );
   QCOMPARE( alg6.group(), QStringLiteral( "testGroup" ) );
+  QCOMPARE( alg6.helpContent(), alg5.helpContent() );
   QgsProcessingModelAlgorithm::ChildAlgorithm alg6c1 = alg6.childAlgorithm( "cx1" );
   QCOMPARE( alg6c1.childId(), QStringLiteral( "cx1" ) );
   QCOMPARE( alg6c1.algorithmId(), QStringLiteral( "buffer" ) );
