Metrics Documentation and Statistics

.rubocop.yml

@@ -18,6 +18,7 @@ Metrics/BlockLength:
     - 'Guardfile'
     - 'spec/**/*_examples.rb'
     - 'spec/**/*_spec.rb'
+    - 'spec/rails_helper.rb'
 
 # Big screens are common :)
 Metrics/LineLength:

app/assets/javascripts/application.js

@@ -12,6 +12,7 @@
 //
 //= require rails-ujs
 //= require turbolinks
+//= require chart.js/dist/Chart.bundle.js
 //= require headroom.js/dist/headroom
 //= require_tree .
 
@@ -44,6 +45,18 @@ document.addEventListener("turbolinks:load", function () {
     });
   }
 
+  document.querySelectorAll('.documentation aside .toggle').forEach(function(toggle) {
+    toggle.addEventListener("click", function() {
+      this.parentNode.classList.toggle('is-active');
+    })
+  });
+
+  Chart.defaults.global.defaultFontFamily = 'Lato, "Helvetica Neue", Helvetica, Arial, sans-serif';
+  Chart.defaults.global.defaultFontSize = 12;
+  Chart.defaults.global.defaultFontStyle = "bold";
+  Chart.defaults.global.animation = 0;
+
+
   document.querySelectorAll("form.search-form").forEach(function(form) {
     form.addEventListener("submit", function() {
       document.querySelectorAll("form.search-form button[type=submit]").forEach(function(button) {

app/assets/javascripts/charts/bar_chart.js

@@ -0,0 +1,45 @@
+var barChart = function(selector, labels, values) {
+  var ctx = document.querySelector(selector)
+                    .getContext('2d');
+
+  new Chart(ctx, {
+    type: "bar",
+    data: {
+      labels: labels,
+      datasets: [
+        {
+          data: values,
+          fill: true,
+          borderWidth: 0,
+          backgroundColor: "rgba(166,20,20,1)"
+        }
+      ]
+    },
+    options: {
+      legend: {
+        display: false
+      },
+      tooltips: {
+        mode: "index",
+        intersect: false,
+        axis: "x"
+      },
+      scales: {
+        xAxes: [
+          {
+            gridLines : {
+              display : false
+            }
+          }
+        ],
+        yAxes: [
+          {
+            ticks: {
+              beginAtZero: true,
+            }
+          }
+        ]
+      }
+    }
+  });
+}

app/assets/javascripts/charts/line_chart.js

@@ -0,0 +1,52 @@
+var lineChart = function(selector, labels, values, scale = "logarithmic") {
+  var ctx = document.querySelector(selector)
+                    .getContext('2d');
+
+  new Chart(ctx, {
+    type: "line",
+    data: {
+      labels: labels,
+      datasets: [
+        {
+          data: values,
+          fill: true,
+          lineTension: 0.2,
+          borderWidth: 5,
+          pointRadius: 1,
+          backgroundColor: "rgba(200,200,200,0.2)",
+          borderColor: "rgba(166,20,20,1)"
+        }
+      ]
+    },
+    options: {
+      legend: {
+        display: false
+      },
+      tooltips: {
+        mode: "index",
+        intersect: false,
+        axis: "x"
+      },
+      scales: {
+        xAxes: [
+          {
+            gridLines : {
+              display : false
+            }
+          }
+        ],
+        yAxes: [
+          {
+            type: scale,
+            ticks: {
+              beginAtZero: true,
+              callback: function(value, index) {
+                if (index % 8 == 0) { return value; }
+              }
+            }
+          }
+        ]
+      }
+    }
+  });
+}

app/assets/stylesheets/application.css.sass

@@ -148,36 +148,12 @@ footer.footer
     @extend .is-size-4
     padding: 0.75rem 0
 
-.project
-  header
-    .score
-      @extend .is-size-5, .has-text-right
 
-  .description
-    @extend .has-text-grey
-    padding: 0.75rem
-
-  .metrics
-    @extend .columns, .is-multiline
-    display: flex
-    strong
-      @extend .is-size-5
-
-    .label
-      @extend .column, .is-2-tablet, .is-12-mobile
-      align-self: flex-end
-      margin-bottom: 0
-
-    .metric
-      @extend .column, .is-3-tablet, .is-6-mobile
-      // Align content to bottom
-      align-self: flex-end
-      strong
-        // Compensate for default icon padding in heading above
-        margin-left: 5px
+.narrow-column
+  @extend .column, .content, .is-three-fifths-desktop, .is-offset-one-fifth-desktop
 
 article.blog-post
-  @extend .column, .content, .is-three-fifths-desktop, .is-offset-one-fifth-desktop
+  @extend .narrow-column
   font-size: 110%
   line-height: 1.7
   table, blockquote

app/assets/stylesheets/components/documentation_page.sass

@@ -0,0 +1,15 @@
+.documentation
+  @extend .columns, .is-multiline
+  aside
+    @extend .column, .is-one-quarter-desktop, .is-full
+    .toggle
+      @extend .is-hidden-desktop, .button, .is-fullwidth
+      margin-bottom: 20px
+    .menu
+      @extend .is-hidden-touch
+
+    &.is-active
+      .menu
+        @extend .is-block-touch
+      .toggle
+        @extend .is-outlined, .is-primary

app/assets/stylesheets/components/project.sass

@@ -0,0 +1,40 @@
+.project
+  header
+    .score
+      @extend .is-size-5, .has-text-right
+
+  .description
+    @extend .has-text-grey
+    padding: 0.75rem
+
+.metrics
+  @extend .columns, .is-multiline
+  display: flex
+  strong
+    @extend .is-size-5
+
+  .label
+    @extend .column, .is-2-tablet, .is-12-mobile
+    align-self: flex-end
+    margin-bottom: 0
+
+  .metric
+    @extend .column, .is-3-tablet, .is-6-mobile
+    // Align content to bottom
+    align-self: flex-end
+    strong
+      // Compensate for default icon padding in heading above
+      margin-left: 5px
+      a
+        color: $black-ter
+
+    .heading
+      a
+        color: $grey-darker
+
+.project-links
+  a.button
+    transition: color 100ms linear
+
+    &:hover
+      color: $primary

app/assets/stylesheets/components/project_list.sass

@@ -0,0 +1,9 @@
+.project-list
+  section
+    > .level
+      padding: 0.5rem 0
+      margin: 0
+      border-bottom: 1px solid $white-ter
+
+      &:last-child
+        border: none

app/assets/stylesheets/components/section_heading.sass

@@ -0,0 +1,12 @@
+.section-heading
+  margin-bottom: 1.5rem
+
+  .level
+    margin: 0
+
+  .content, .content strong
+    color: $grey-dark
+
+  .level-right
+    .button
+      @extend .is-primary, .is-outlined

app/helpers/application_helper.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module ApplicationHelper
+  include ComponentHelpers
+  include StatsHelpers
+
   def metric_icon(metric)
     "fa-" + t(:icon, scope: "metrics.#{metric}")
   end
@@ -9,18 +12,62 @@ def metric_label(metric)
     t(:label, scope: "metrics.#{metric}")
   end
 
-  def project_metrics(project, *metrics)
-    metrics.map do |metric|
-      render partial: "projects/metric", locals: {
-        label: metric_label(metric),
-        value: project.public_send(metric),
-        icon:  metric_icon(metric),
-      }
-    end.inject(&:+)
+  # This should be refactored...
+  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  def pretty_metric_value(value)
+    if value.is_a?(Float) || value.is_a?(BigDecimal)
+      number_with_delimiter(value.floor) + "%"
+    elsif value.is_a? Integer
+      number_with_delimiter value
+    elsif value.is_a?(Date) || value.is_a?(Time)
+      content_tag "time", "#{time_ago_in_words(value)} ago", datetime: value.iso8601, title: l(value)
+    elsif value.is_a? Array
+      value.to_sentence
+    else
+      value
+    end
   end
+  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-  def project_link(label, url, icon:)
-    render partial: "projects/link", locals: { label: label, url: url, icon: icon }
+  #
+  # A little utility method for displaying project rankings like most downloaded gems
+  # in metrics docs pages without too much repetition of in-view logic
+  #
+  # rubocop:disable Metrics/ParameterLists It's not great but I'm ok with it here
+  def project_ranking(title, scope: Project.for_display, table:, column:, direction: "DESC", description: nil)
+    projects = scope.order("#{table}.#{column} #{direction} NULLS LAST").limit(100)
+    metrics = if table == :github_repos
+                ["github_repo_stargazers_count", "github_repo_#{column}"].uniq
+              else
+                ["rubygem_downloads", "rubygem_#{column}"].uniq
+              end
+
+    project_list projects, title: title, metrics: metrics, description: description
+  end
+  # rubocop:enable Metrics/ParameterLists
+
+  def docs
+    @docs ||= Docs.new
+  end
+
+  def link_to_docs_if_exists(page, &block)
+    content = capture(&block)
+
+    if docs.find page
+      link_to content, page_path(page)
+    else
+      content
+    end
+  end
+
+  # Render given text as markdown. Do not use this with unsafe
+  # inputs as it does not use any blacklisting or sanitization!
+  def markdown(text)
+    Redcarpet::Markdown.new(
+      Redcarpet::Render::HTML,
+      autolink: true,
+      tables:   true
+    ).render(text).html_safe # rubocop:disable Rails/OutputSafety
   end
 
   # why
@@ -60,60 +107,7 @@ def description
     content_for(:description).presence || t(:description)
   end
 
-  DISTANCES = {
-    1.week   => "within last week",
-    2.weeks  => "within last two weeks",
-    1.month  => "within last month",
-    3.months => "within last 3 months",
-    1.year   => "within last year",
-    2.years  => "within last 2 years",
-  }.freeze
-
-  def recent_distance_in_words(time)
-    return if time.blank?
-
-    matching_distance = DISTANCES.find do |distance, _label|
-      time >= distance.ago
-    end
-
-    matching_distance&.last || "more than 2 years ago"
-  end
-
   def active_when(controller:)
     "is-active" if controller_name == controller.to_s
   end
-
-  def category_card(category, compact: false, inline: false)
-    extra_classes = inline ? %w[inline] : []
-    locals = {
-      category:      category,
-      compact:       compact,
-      extra_classes: extra_classes,
-    }
-    render partial: "components/category_card", locals: locals
-  end
-
-  def project_health_tags(project)
-    render "components/project_health_tags", project: project
-  end
-
-  def project_health_tag(health_status)
-    render "components/project_health_tag", status: health_status
-  end
-
-  def project_order_dropdown(order)
-    render "components/project_order_dropdown", order: order
-  end
-
-  def landing_hero(title:, image:, &block)
-    render "components/landing_hero", title: title, image: image, &block
-  end
-
-  def landing_feature(title:, image:, &block)
-    render "components/landing_feature", title: title, image: image, &block
-  end
-
-  def component_example(heading, &block)
-    render "components/component_example", heading: heading, &block
-  end
 end