Proper styling of help-text in custom functions (@qgsfunction) - html-code

Question

I would like to have a QGIS-like-styling of the help-text of custom functions.

I.e. the html-code <h3>text</h3> creates the green headline. Are there theme fonts or other definitions (colors...) for the other elements of the help-text known (marked by <?>...</?> in the picture below)?

Alternatively - where can I find the files with the core-expressions to look there for the definitions of help-text in my qgis-installation-directory?

Answer 1

In the source code, there are 3 files for me :

• a file for function description (/resources/function_help/json/) :

{
  "name": "env",
  "type": "function",
  "description": "Gets an environment variable and returns its content as a string. If the variable is not found, `NULL` will be returned. This is handy to inject system specific configuration like drive letters or path prefixes. Definition of environment variables depends on the operating system, please check with your system administrator or the operating system documentation how this can be set.",
  "arguments": [
    {"arg":"name","description":"The name of the environment variable which should be retrieved."}
  ],
  "examples": [
    { "expression":"env( 'LANG' )", "returns":"'en_US.UTF-8'"},
    { "expression":"env( 'MY_OWN_PREFIX_VAR' )", "returns":"'Z:'"},
    { "expression":"env( 'I_DO_NOT_EXIST' )", "returns":"NULL"}
  ]
}

• a file for produce a template from the json help function file (/scripts/process_function_template.py)

• the function QgsExpression.helpText (/src/core/expression/qgsexpression.cpp) that contains all the html formatting style :

QString QgsExpression::helpText( QString name )
{
  QgsExpression::initFunctionHelp();

  if ( !sFunctionHelpTexts.contains( name ) )
    return tr( "function help for %1 missing" ).arg( name );

  const Help &f = sFunctionHelpTexts[ name ];

  name = f.mName;
  if ( f.mType == tr( "group" ) )
  {
    name = group( name );
    name = name.toLower();
  }

  name = name.toHtmlEscaped();

  QString helpContents( QStringLiteral( "<h3>%1</h3>\n<div class=\"description\"><p>%2</p></div>" )
                        .arg( tr( "%1 %2" ).arg( f.mType, name ),
                              f.mDescription ) );

  for ( const HelpVariant &v : qgis::as_const( f.mVariants ) )
  {
    if ( f.mVariants.size() > 1 )
    {
      helpContents += QStringLiteral( "<h3>%1</h3>\n<div class=\"description\">%2</p></div>" ).arg( v.mName, v.mDescription );
    }

    if ( f.mType != tr( "group" ) && f.mType != tr( "expression" ) )
      helpContents += QStringLiteral( "<h4>%1</h4>\n<div class=\"syntax\">\n" ).arg( tr( "Syntax" ) );

    if ( f.mType == tr( "operator" ) )
    {
      if ( v.mArguments.size() == 1 )
      {
        helpContents += QStringLiteral( "<code><span class=\"functionname\">%1</span> <span class=\"argument\">%2</span></code>" )
                        .arg( name, v.mArguments[0].mArg );
      }
      else if ( v.mArguments.size() == 2 )
      {
        helpContents += QStringLiteral( "<code><span class=\"argument\">%1</span> <span class=\"functionname\">%2</span> <span class=\"argument\">%3</span></code>" )
                        .arg( v.mArguments[0].mArg, name, v.mArguments[1].mArg );
      }
    }
    else if ( f.mType != tr( "group" ) && f.mType != tr( "expression" ) )
    {
      helpContents += QStringLiteral( "<code><span class=\"functionname\">%1</span>" ).arg( name );

      bool hasOptionalArgs = false;

      if ( f.mType == tr( "function" ) && ( f.mName[0] != '$' || !v.mArguments.isEmpty() || v.mVariableLenArguments ) )
      {
        helpContents += '(';

        QString delim;
        for ( const HelpArg &a : qgis::as_const( v.mArguments ) )
        {
          if ( !a.mDescOnly )
          {
            if ( a.mOptional )
            {
              hasOptionalArgs = true;
              helpContents += QStringLiteral( "[" );
            }

            helpContents += delim;
            helpContents += QStringLiteral( "<span class=\"argument\">%2%3</span>" ).arg(
                              a.mArg,
                              a.mDefaultVal.isEmpty() ? QString() : '=' + a.mDefaultVal
                            );

            if ( a.mOptional )
              helpContents += QStringLiteral( "]" );
          }
          delim = QStringLiteral( "," );
        }

        if ( v.mVariableLenArguments )
        {
          helpContents += QChar( 0x2026 );
        }

        helpContents += ')';
      }

      helpContents += QLatin1String( "</code>" );

      if ( hasOptionalArgs )
      {
        helpContents += QLatin1String( "<br/><br/>" ) + tr( "[ ] marks optional components" );
      }
    }

    if ( !v.mArguments.isEmpty() )
    {
      helpContents += QStringLiteral( "<h4>%1</h4>\n<div class=\"arguments\">\n<table>" ).arg( tr( "Arguments" ) );

      for ( const HelpArg &a : qgis::as_const( v.mArguments ) )
      {
        if ( a.mSyntaxOnly )
          continue;

        helpContents += QStringLiteral( "<tr><td class=\"argument\">%1</td><td>%2</td></tr>" ).arg( a.mArg, a.mDescription );
      }

      helpContents += QLatin1String( "</table>\n</div>\n" );
    }

    if ( !v.mExamples.isEmpty() )
    {
      helpContents += QStringLiteral( "<h4>%1</h4>\n<div class=\"examples\">\n<ul>\n" ).arg( tr( "Examples" ) );

      for ( const HelpExample &e : qgis::as_const( v.mExamples ) )
      {
        helpContents += "<li><code>" + e.mExpression + "</code> &rarr; <code>" + e.mReturns + "</code>";

        if ( !e.mNote.isEmpty() )
          helpContents += QStringLiteral( " (%1)" ).arg( e.mNote );

        helpContents += QLatin1String( "</li>\n" );
      }

      helpContents += QLatin1String( "</ul>\n</div>\n" );
    }

    if ( !v.mNotes.isEmpty() )
    {
      helpContents += QStringLiteral( "<h4>%1</h4>\n<div class=\"notes\"><p>%2</p></div>\n" ).arg( tr( "Notes" ), v.mNotes );
    }
  }

  return helpContents;
}