class GrafanaReporter::Asciidoctor::Help

This class generates the functional help documentation for the asciidoctor report. It can create the documentation for github markdown, as well as in asciidoctor syntax.

Public Instance Methods

asciidoctor(headline_level = 2) click to toggle source

@param headline_level [Integer] top level of headline @return [String] asciidoctor compatible documentation

# File lib/grafana_reporter/asciidoctor/help.rb, line 12
def asciidoctor(headline_level = 2)
  help_text(asciidoctor_options.merge(level: headline_level))
end
github(headline_level = 2) click to toggle source

@param headline_level [Integer] top level of headline @return [String] github markdown compatible documentation

# File lib/grafana_reporter/asciidoctor/help.rb, line 18
def github(headline_level = 2)
  "#{toc}\n\n#{help_text(github_options.merge(level: headline_level))}"
end

Private Instance Methods

asciidoctor_options() click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 28
def asciidoctor_options
  { headline_separator: '=', code_begin: '`+', code_end: '+`', table_begin: "\n[%autowidth.stretch, "\
    "options=\"header\"]\n|===\n", table_end: "\n|===" }
end
functions_as_text(opts = {}) click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 73
      def functions_as_text(opts = {})
        opts = { level: 3, headline_separator: '=' }.merge(opts)
        result = []

        prepared_help[:functions].sort.map do |k, v|
          result << %(
#{opts[:headline_separator] * opts[:level]} #{opts[:code_begin]}#{k}#{opts[:code_end]}
Usage: #{opts[:code_begin]}#{v[:call]}#{opts[:code_end]}

#{v[:description]}#{"\n\nSee also: #{v[:see]}" if v[:see]}#{unless v[:options].empty?
%(
#{opts[:table_begin]}| Option | Description#{"\n#{opts[:head_postfix_col] * 2}" if opts[:head_postfix_col]}
#{v[:options].sort.map { |_opt_k, opt_v| "| #{opts[:code_begin]}#{opt_v[:call]}#{opts[:code_end]} | #{opt_v[:description].gsub('|', '\|')}" }.join("\n") }#{opts[:table_end]})
end}
)
        end

        result.join
      end
github_options() click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 24
def github_options
  { headline_separator: '#', code_begin: '`', code_end: '`', table_begin: "\n", head_postfix_col: '| -- ' }
end
global_options_as_text(opts = {}) click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 57
      def global_options_as_text(opts = {})
        opts = { level: 3 }.merge(opts)
        result = []

        prepared_help[:global_options].sort.map do |k, v|
          result << %(
#{opts[:headline_separator] * opts[:level]} #{opts[:code_begin]}#{k}#{opts[:code_end]}
Usage: #{opts[:code_begin]}#{v['call']}#{opts[:code_end]}

#{v['description']}
)
        end

        result.join
      end
help_text(opts) click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 33
      def help_text(opts)
        %(#{opts[:headline_separator] * opts[:level]} Global options
#{global_options_as_text(opts.merge(level: opts[:level] + 1))}
#{opts[:headline_separator] * opts[:level]} Functions
#{functions_as_text(opts.merge(level: opts[:level] + 1))})
      end
prepared_help() click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 93
def prepared_help
  yaml = YAML.safe_load(raw_help_yaml)

  result = {}
  result[:functions] = {}
  result[:global_options] = yaml['global_options']

  functions = result[:functions]
  std_opts = yaml['standard_options']
  yaml.reject { |k, _v| k =~ /.*_options$/ }.each_key do |key|
    functions[key] = {}
    res_item = functions[key]
    res_item[:options] = {}

    item = yaml[key]
    res_item[:call] = item['call']
    res_item[:description] = item['description']
    res_item[:see] = item['see']

    opts = ((item['options'] ? item['options'].keys : [])
            (item['standard_options'] ? item['standard_options'].keys : [])).sort
    opts.each do |opt_key|
      res_item[:options][opt_key] = {}

      if item['standard_options'].key?(opt_key)
        res_item[:options][opt_key][:call] = std_opts[opt_key]['call']
        res_item[:options][opt_key][:description] = "#{std_opts[opt_key]['description']} "\
                                                    "#{item['standard_options'][opt_key]}".chop
        res_item[:options][opt_key][:see] = std_opts[opt_key]['see'] if std_opts[opt_key]['see']
      else
        res_item[:options][opt_key][:call] = item['options'][opt_key]['call']
        res_item[:options][opt_key][:description] = item['options'][opt_key]['description']
        res_item[:options][opt_key][:see] = item['options'][opt_key]['see'] if item['options'][opt_key]['see']
      end
    end
  end

  result
end
raw_help_yaml() click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 133
      def raw_help_yaml
        <<~YAML_HELP
          global_options:
            grafana_default_instance:
              call: ":grafana_default_instance: <instance_name>"
              description: >-
                Specifies which grafana instance shall be used. If not set, the grafana instance names `default`
                will be used.

            grafana_default_dashboard:
              call: ":grafana_default_dashboard: <dashboard_uid>"
              description: >-
                Specifies to which dashboard the queries shall be targeted by default.

            grafana_default_from_timezone:
              call: ":grafana_default_from_timezone: <timezone>"
              description: Specifies which timezone shall be used for the `from` time, e.g. `CET` or `CEST`.

            grafana_default_to_timezone:
              call: ":grafana_default_to_timezone: <timezone>"
              description: Specifies which timezone shall be used for the `to` time, e.g. `CET` or `CEST`.

            from:
              call: ":from: <from_timestamp>"
              description: >-
                Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
                properly to timestamps relative to the called time.

            to:
              call: ":to: <to_timestamp>"
              description: >-
                Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
                properly to timestamps relative to the called time.

          standard_options:
            instance:
              call: instance="<instance_name>"
              description: >-
                can be used to override global grafana instance, set in the report with `grafana_default_instance`.
                If nothing is set, the configured grafana instance with name `default` will be used.

            dashboard:
              call: dashboard="<dashboard_uid>"
              description: >-
                Specifies the dashboard to be used. If `grafana_default_dashboard` is specified in the report template,
                this value can be overridden with this option.

            from:
              call: from="<timestamp>"
              description: can be used to override default `from` time

            from_timezone:
              call: from_timezone="<timezone>"
              description: can be used to override system timezone for `from` time and will also override `grafana_default_from_timezone` option

            to_timezone:
              call: to_timezone="<timezone>"
              description: can be used to override system timezone for `to` time and will also override `grafana_default_to_timezone` option

            to:
              call: to="<timestamp>"
              description: can be used to override default `to` time

            format:
              call: format="<format_col1>,<format_col2>,..."
              description: >-
                Specify format in which the results shall be returned, e.g. `%.2f` for only two digit decimals of a
                float. Several columns are separated by `,`. Execution is applied in the following order `format`,
                `replace_values`, `filter_columns`, `transpose`.
              see: 'https://ruby-doc.org/core/Kernel.html#method-i-sprintf'

            replace_values:
              call: replace_values="<replace_1>:<with_1>,<replace_2>:<with_2>,..."
              description: >-
                Specify result values which shall be replaced, e.g. `2:OK` will replace query values `2` with value `OK`.
                Replacing several values is possible by separating by `,`. Matches with regular expressions are also
                supported, but must be full matches, i.e. have to start with `^` and end with `$`, e.g. `^[012]$:OK`.
                Number replacements can also be performed, e.g. `<8.2` or `<>3`. Execution is applied in the following order `format`,
                `replace_values`, `filter_columns`, `transpose`.
              see: https://ruby-doc.org/core/Regexp.html#class-Regexp-label-Character+Classes

            filter_columns:
              call: filter_columns="<column_name_1>,<column_name_2>,..."
              description: >-
                Removes specified columns from result. Execution is applied in the following order `format`, `replace_values`,
                `filter_columns`, `transpose`.

            transpose:
              call: transpose="true"
              description: >-
                Transposes the query result, i.e. columns become rows and rows become columnns. Execution is applied in the
                following order `format`, `replace_values`, `filter_columns`, `transpose`.

            column_divider:
              call: column_divider="<divider>"
              description: >-
                Replace the default column divider with another one, when used in conjunction with `table_formatter` set to
                `adoc_deprecated`. Defaults to ` | ` for being interpreted as a asciidoctor column. DEPRECATED: switch to
                `table_formatter` named `adoc_plain`, or implement a custom table formatter.

            row_divider:
              call: row_divider="<divider>"
              description: >-
                Replace the default row divider with another one, when used in conjunction with `table_formatter` set to
                `adoc_deprecated`. . Defaults to `| ` for being interpreted as a asciidoctor row. DEPRECATED: switch to
                `table_formatter` named `adoc_plain`, or implement a custom table formatter.

            table_formatter:
              call: table_formatter="<formatter>"
              description: >-
                Specify a table formatter fitting for your expected target format. It defaults to `adoc_plain` for asciidoctor
                templates and to `csv` for all other templates, e.g. ERB.

            timeout:
              call: timeout="<timeout_in_seconds>"
              description: >-
                Set a timeout for the current query. If not overridden with `grafana_default_timeout` in the report template,
                this defaults to 60 seconds.

          # ----------------------------------
          # FUNCTION DOCUMENTATION STARTS HERE
          # ----------------------------------

          grafana_help:
            description: Show all available grafana calls within the asciidoctor templates, including available options.
            call: 'include::grafana_help[]'

          grafana_environment:
            description: Shows all available variables in the rendering context which can be used in the asciidoctor template.
            call: 'include::grafana_environment[]'

          grafana_alerts:
            description: >-
              Returns a table of active alert states including the specified columns and the connected information. Supports
              all query parameters from the Grafana Alerting API, such as `query`, `state`, `limit`, `folderId` and others.
            call: 'include::grafana_alerts[columns="<column_name_1>,<column_name_2>,...",options]'
            see: https://grafana.com/docs/grafana/latest/http_api/alerting/#get-alerts
            options:
              columns:
                description: >-
                  Specifies columns that shall be returned. Valid columns are `id`, `dashboardId`, `dashboardUId`, `dashboardSlug`,
                  `panelId`, `name`, `state`, `newStateDate`, `evalDate`, `evalData` and `executionError`.
                call: columns="<column_name_1>,<columns_name_2>,..."
              panel:
                description: >-
                  If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard`
                  or `grafana_default_dashboard` is set.
                call: panel="<panel_id>"
            standard_options:
              column_divider:
              dashboard: >-
                If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to
                this dashboard. To show all alerts in this case, specify `dashboard=""` as option.
              filter_columns:
              format:
              from:
              instance:
              replace_values:
              row_divider:
              table_formatter:
              timeout:
              to:
              transpose:
              from_timezone:
              to_timezone:

          grafana_annotations:
            description: >-
              Returns a table of all annotations, matching the specified filter criteria and the specified columns. Supports all
              query parameters from the Grafana Alerting API, such as `limit`, `alertId`, `panelId` and others.
            call: 'include::grafana_annotations[columns="<column_name_1>,<column_name_2>,...",options]'
            see: https://grafana.com/docs/grafana/latest/http_api/annotations/#find-annotations
            options:
              columns:
                description: >-
                  Specified the columns that shall be returned. Valid columns are `id`, `alertId`, `dashboardId`, `panelId`, `userId`,
                  `userName`, `newState`, `prevState`, `time`, `timeEnd`, `text`, `metric` and `type`.
                call: columns="<column_name_1>,<columns_name_2>,..."
              panel:
                description: >-
                  If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard` or
                  `grafana_default_dashboard` is set.
                call: panel="<panel_id>"
            standard_options:
              column_divider:
              dashboard: >-
                If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to this
                dashboard. To show all alerts in this case, specify `dashboard=""` as option.
              filter_columns:
              format:
              from:
              instance:
              replace_values:
              row_divider:
              table_formatter:
              timeout:
              to:
              transpose:
              from_timezone:
              to_timezone:

          grafana_panel_property:
            description: >-
              Returns a property field for the specified panel. `<type>` can either be `title` or `description`.
              Grafana variables will be replaced in the returned value.
            call: 'grafana_panel_property:<panel_id>["<type>",options]'
            see: https://grafana.com/docs/grafana/latest/variables/syntax/
            standard_options:
              dashboard:
              instance:

          grafana_panel_image:
            description: Includes a panel image as an image in the document. Can be called for inline-images as well as for blocks.
            call: 'grafana_panel_image:<panel_id>[options] or grafana_panel_image::<panel_id>[options]'
            options:
              render-height:
                description: can be used to override default `height` in which the panel shall be rendered
                call: render-height="<height>"
              render-width:
                description: can be used to override default `width` in which the panel shall be rendered
                call: render-width="<width>"
              render-theme:
                description: can be used to override default `theme` in which the panel shall be rendered (light by default)
                call: render-theme="<theme>"
              render-timeout:
                description: can be used to override default `timeout` in which the panel shall be rendered (60 seconds by default)
                call: render-timeout="<timeout>"
            standard_options:
              dashboard:
              from:
              instance:
              timeout:
              to:
              from_timezone:
              to_timezone:

          grafana_panel_query_table:
            description: >-
              Returns the results of a query, which is configured in a grafana panel, as a table in asciidoctor.
              Grafana variables will be replaced in the panel's SQL statement.
            call: 'include::grafana_panel_query_table:<panel_id>[query="<query_letter>",options]'
            see: https://grafana.com/docs/grafana/latest/variables/syntax/
            options:
              query:
                call: query="<query_letter>"
                description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
            standard_options:
              column_divider:
              dashboard:
              filter_columns:
              format:
              from:
              instance:
              replace_values:
              row_divider:
              table_formatter:
              timeout:
              to:
              transpose:
              from_timezone:
              to_timezone:

          grafana_panel_query_value:
            call: 'grafana_panel_query_value:<panel_id>[query="<query_letter>",options]'
            description: >-
              Returns the value in the first column and the first row of a query, which is configured in a grafana panel.
              Grafana variables will be replaced in the panel's SQL statement.
            see: https://grafana.com/docs/grafana/latest/variables/syntax/
            options:
              query:
                call: query="<query_letter>"
                description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
            standard_options:
              dashboard:
              filter_columns:
              format:
              from:
              instance:
              replace_values:
              timeout:
              to:
              from_timezone:
              to_timezone:

          grafana_sql_table:
            call: 'include::grafana_sql_table:<datasource_id>[sql="<sql_query>",options]'
            description: >-
              Returns a table with all results of the given query.
              Grafana variables will be replaced in the SQL statement.
            see: https://grafana.com/docs/grafana/latest/variables/syntax/
            standard_options:
              column_divider:
              filter_columns:
              format:
              from:
              instance:
              replace_values:
              row_divider:
              table_formatter:
              timeout:
              to:
              transpose:
              from_timezone:
              to_timezone:

          grafana_sql_value:
            call: 'grafana_sql_value:<datasource_id>[sql="<sql_query>",options]'
            description: >-
              Returns the value in the first column and the first row of the given query.
              Grafana variables will be replaced in the SQL statement.
            see: https://grafana.com/docs/grafana/latest/variables/syntax/
            standard_options:
              filter_columns:
              format:
              from:
              instance:
              replace_values:
              timeout:
              to:
              from_timezone:
              to_timezone:
        YAML_HELP
      end
toc() click to toggle source
# File lib/grafana_reporter/asciidoctor/help.rb, line 40
def toc
  result = []

  result << 'Table of contents'
  result << '* [Global options](#global-options)'
  prepared_help[:global_options].sort.map do |k, _v|
    result << "  * [#{k}](##{k.downcase})"
  end

  result << '* [Functions](#functions)'
  prepared_help[:functions].sort.map do |k, _v|
    result << "  * [#{k}](##{k.downcase})"
  end

  result.join("\n")
end