Merge branch '322103-optimize-the-dictionary-view-to-not-repeat-same-columns' into 'master'

Optimize the Dictionary view to not repeat same columns

See merge request gitlab-org/gitlab!55145

changelogs/unreleased/322103-optimize-the-dictionary-view-to-not-repeat-same-columns.yml

+---
+title: Optimize Metrics Dictionary
+merge_request: 55145
+author:
+type: changed

lib/gitlab/usage/docs/helper.rb

@@ -5,9 +5,6 @@ module Gitlab
     module Docs
       # Helper with functions to be used by HAML templates
       module Helper
-        HEADER = %w(field value).freeze
-        SKIP_KEYS = %i(description).freeze
-
         def auto_generated_comment
           <<-MARKDOWN.strip_heredoc
             ---
@@ -27,37 +24,33 @@ module Gitlab
         end
 
         def render_name(name)
-          "## `#{name}`\n"
+          "### `#{name}`"
         end
 
         def render_description(object)
-          return 'Missing description' unless object.attributes[:description].present?
+          return 'Missing description' unless object[:description].present?
 
-          object.attributes[:description]
+          object[:description]
         end
 
-        def render_attribute_row(key, value)
-          value = Gitlab::Usage::Docs::ValueFormatter.format(key, value)
-          table_row(["`#{key}`", value])
+        def render_yaml_link(yaml_path)
+          "[YAML definition](#{yaml_path})"
         end
 
-        def render_attributes_table(object)
-          <<~MARKDOWN
+        def render_status(object)
+          "Status: #{format(:status, object[:status])}"
+        end
 
-            #{table_row(HEADER)}
-            #{table_row(HEADER.map { '---' })}
-            #{table_value_rows(object.attributes)}
-          MARKDOWN
+        def render_owner(object)
+          "Group: `#{object[:product_group]}`"
         end
 
-        def table_value_rows(attributes)
-          attributes.reject { |k, _| k.in?(SKIP_KEYS) }.map do |key, value|
-            render_attribute_row(key, value)
-          end.join("\n")
+        def render_tiers(object)
+          "Tiers: #{format(:tier, object[:tier])}"
         end
 
-        def table_row(array)
-          "| #{array.join(' | ')} |"
+        def format(key, value)
+          Gitlab::Usage::Docs::ValueFormatter.format(key, value)
         end
       end
     end

lib/gitlab/usage/docs/templates/default.md.haml

@@ -16,13 +16,23 @@
   - [`config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/metrics)
   - [`ee/config/metrics`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/config/metrics)
 
-Each table includes a `milestone`, which corresponds to the GitLab version when the metric
-was released.
+  Each table includes a `milestone`, which corresponds to the GitLab version when the metric
+  was released.
+
+  ## Metrics Definitions
+
 \
 - metrics_definitions.each do |name, object|
 
   = render_name(name)
-
-  = render_description(object)
-
-  = render_attributes_table(object)
+  \
+  = render_description(object.attributes)
+  \
+  = render_yaml_link(object.yaml_path)
+  \
+  = render_owner(object.attributes)
+  \
+  = render_status(object.attributes)
+  \
+  = render_tiers(object.attributes)
+  \

lib/gitlab/usage/docs/value_formatter.rb

@@ -12,12 +12,12 @@ module Gitlab
             "**`#{value}`**"
           when :data_source
             value.to_s.capitalize
-          when :product_group, :product_category
+          when :product_group, :product_category, :status
             "`#{value}`"
           when :introduced_by_url
             "[Introduced by](#{value})"
           when :distribution, :tier
-            Array(value).join(', ')
+            Array(value).map { |tier| "`#{tier}`" }.join(', ')
           else
             value
           end

lib/gitlab/usage/metric_definition.rb

@@ -4,6 +4,7 @@ module Gitlab
   module Usage
     class MetricDefinition
       METRIC_SCHEMA_PATH = Rails.root.join('config', 'metrics', 'schema.json')
+      BASE_REPO_PATH = 'https://gitlab.com/gitlab-org/gitlab/-/blob/master'
 
       attr_reader :path
       attr_reader :attributes
@@ -21,6 +22,10 @@ module Gitlab
         attributes
       end
 
+      def yaml_path
+        "#{BASE_REPO_PATH}#{path.delete_prefix(Rails.root.to_s)}"
+      end
+
       def validate!
         unless skip_validation?
           self.class.schemer.validate(attributes.stringify_keys).each do |error|

spec/lib/gitlab/usage/docs/renderer_spec.rb

@@ -2,6 +2,8 @@
 
 require 'spec_helper'
 
+CODE_REGEX = %r{<code>(.*)</code>}.freeze
+
 RSpec.describe Gitlab::Usage::Docs::Renderer do
   describe 'contents' do
     let(:dictionary_path) { Gitlab::Usage::Docs::Renderer::DICTIONARY_PATH }
@@ -9,12 +11,12 @@ RSpec.describe Gitlab::Usage::Docs::Renderer do
 
     it 'generates dictionary for given items' do
       generated_dictionary = described_class.new(items).contents
+
       generated_dictionary_keys = RDoc::Markdown
         .parse(generated_dictionary)
         .table_of_contents
-        .select { |metric_doc| metric_doc.level == 2 && !metric_doc.text.start_with?('info:') }
-        .map(&:text)
-        .map { |text| text.sub('<code>', '').sub('</code>', '') }
+        .select { |metric_doc| metric_doc.level == 3 }
+        .map { |item| item.text.match(CODE_REGEX)&.captures&.first }
 
       expect(generated_dictionary_keys).to match_array(items.keys)
     end

spec/lib/gitlab/usage/docs/value_formatter_spec.rb

@@ -10,11 +10,11 @@ RSpec.describe Gitlab::Usage::Docs::ValueFormatter do
       :data_source       | 'redis'                        | 'Redis'
       :data_source       | 'ruby'                         | 'Ruby'
       :introduced_by_url | 'http://test.com'              | '[Introduced by](http://test.com)'
-      :tier              | %w(gold premium)               | 'gold, premium'
-      :distribution      | %w(ce ee)                      | 'ce, ee'
+      :tier              | %w(gold premium)               | '`gold`, `premium`'
+      :distribution      | %w(ce ee)                      | '`ce`, `ee`'
       :key_path          | 'key.path'                     | '**`key.path`**'
       :milestone         | '13.4'                         | '13.4'
-      :status            | 'data_available'               | 'data_available'
+      :status            | 'data_available'               | '`data_available`'
     end
 
     with_them do