我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

此版本的 GitHub Enterprise 将停止服务 此版本的 GitHub Enterprise 已停止服务 2020-11-12. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

将数据渲染为图形

了解如何使用 D3.js 库和 Ruby Octokit 可视化仓库中的编程语言。

本文内容

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。

在本指南中,我们将使用 API 来获取有关我们拥有的仓库以及构成这些仓库的编程语言的信息。 然后,我们将使用 D3.js 库来以几种不同的方式可视化这些信息。 为了与 GitHub Enterprise API 进行交互,我们将使用卓越的 Ruby 库 Octokit

在开始本示例之前,您应该阅读“身份验证基础知识”指南(如果尚未阅读)。 您可以在平台样本仓库中找到此项目的完整源代码。

我们马上开始!

设置 OAuth 应用程序

首先,请在 GitHub Enterprise 上注册一个新应用程序。 将主 URL 和回调 URL 设置为 http://localhost:4567/。 与之前一样,我们将使用 sinatra-auth-github 实现 Rack 中间件,以处理 API 的身份验证:

require 'sinatra/auth/github'

module Example
  class MyGraphApp < Sinatra::Base
    # !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!!
    # Instead, set and test environment variables, like below
    # if ENV['GITHUB_CLIENT_ID'] && ENV['GITHUB_CLIENT_SECRET']
    #  CLIENT_ID        = ENV['GITHUB_CLIENT_ID']
    #  CLIENT_SECRET    = ENV['GITHUB_CLIENT_SECRET']
    # end

    CLIENT_ID = ENV['GH_GRAPH_CLIENT_ID']
    CLIENT_SECRET = ENV['GH_GRAPH_SECRET_ID']

    enable :sessions

    set :github_options, {
      :scopes    => "repo",
      :secret    => CLIENT_SECRET,
      :client_id => CLIENT_ID,
      :callback_url => "/"
    }

    register Sinatra::Auth::Github

    get '/' do
      if !authenticated?
        authenticate!
      else
        access_token = github_user["token"]
      end
    end
  end
end

设置与上一个示例类似的 config.ru 文件:

ENV['RACK_ENV'] ||= 'development'
require "rubygems"
require "bundler/setup"

require File.expand_path(File.join(File.dirname(__FILE__), 'server'))

run Example::MyGraphApp

获取仓库信息

这次,为了与 GitHub Enterprise API 进行对话,我们将使用 Octokit.rb。 这比直接进行一大堆 REST 调用要容易得多。 另外,Octokit 是由 GitHubber 开发的,并且一直在积极维护,因此可以确保有效性。

通过 Octokit 进行 API 身份验证非常简单。 只需将您的登录名和令牌传递到 Octokit::Client 构造函数:

if !authenticated?
  authenticate!
else
  octokit_client = Octokit::Client.new(:login => github_user.login, :oauth_token => github_user.token)
end

我们来用仓库的数据做一些有趣的事情。 我们将看到它们使用的不同编程语言,并计算出哪些是最常用的。 为此,我们首先需要从 API 获取仓库列表。 使用 Octokit 时,其代码如下所述:

repos = client.repositories

接下来,我们将遍历每个仓库,并计算 GitHub Enterprise 与之关联的语言:

language_obj = {}
repos.each do |repo|
  # sometimes language can be nil
  if repo.language
    if !language_obj[repo.language]
      language_obj[repo.language] = 1
    else
      language_obj[repo.language] += 1
    end
  end
end

languages.to_s

当您重新启动服务器时,您的 web 页面应显示如下代码:

{"JavaScript"=>13, "PHP"=>1, "Perl"=>1, "CoffeeScript"=>2, "Python"=>1, "Java"=>3, "Ruby"=>3, "Go"=>1, "C++"=>1}

到目前为止,进展不错,但结果不是很人性化。 可视化将非常有助于我们理解这些语言计数是如何分布的。 我们来将这些计数输入到 D3 中,得到一个表示语言使用频率的简洁条形图。

可视化语言计数

D3.js(或仅 D3)是用于创建多种图表、图形和交互式可视化内容的综合库。 详细介绍 D3 的用法超出了本指南的范围,但我们推荐您阅读一篇不错的介绍性文章“D3 for Mortals(面向大众的 D3)”

D3 是一个JavaScript 库,喜欢以数组的形式处理数据。 因此,让我们将 Ruby 哈希转换为 JSON 数组,以供浏览器中的 JavaScript 使用。

languages = []
language_obj.each do |lang, count|
  languages.push :language => lang, :count => count
end

erb :lang_freq, :locals => { :languages => languages.to_json}

我们只需遍历对象中的每个键值对,然后将它们推入新的数组。 我们之前没有这样做是因为我们不想在创建 language_obj 对象的过程中遍历它。

现在,lang_freq.erb 将需要一些 JavaScript 来支持渲染条形图。 以后,您只需使用此处提供的代码,如果您想详细了解 D3 的工作原理,您可以参考上面链接的资源:

<!DOCTYPE html>
<meta charset="utf-8">
<html>
  <head>
    <script src="//cdnjs.cloudflare.com/ajax/libs/d3/3.0.1/d3.v3.min.js"></script>
    <style>
    svg {
      padding: 20px;
    }
    rect {
      fill: #2d578b
    }
    text {
      fill: white;
    }
    text.yAxis {
      font-size: 12px;
      font-family: Helvetica, sans-serif;
      fill: black;
    }
    </style>
  </head>
  <body>
    <p>Check this sweet data out:</p>
    <div id="lang_freq"></div>

  </body>
  <script>
    var data = <%= languages %>;

    var barWidth = 40;
    var width = (barWidth + 10) * data.length;
    var height = 300;

    var x = d3.scale.linear().domain([0, data.length]).range([0, width]);
    var y = d3.scale.linear().domain([0, d3.max(data, function(datum) { return datum.count; })]).
      rangeRound([0, height]);

    // add the canvas to the DOM
    var languageBars = d3.select("#lang_freq").
      append("svg:svg").
      attr("width", width).
      attr("height", height);

    languageBars.selectAll("rect").
      data(data).
      enter().
      append("svg:rect").
      attr("x", function(datum, index) { return x(index); }).
      attr("y", function(datum) { return height - y(datum.count); }).
      attr("height", function(datum) { return y(datum.count); }).
      attr("width", barWidth);

    languageBars.selectAll("text").
      data(data).
      enter().
      append("svg:text").
      attr("x", function(datum, index) { return x(index) + barWidth; }).
      attr("y", function(datum) { return height - y(datum.count); }).
      attr("dx", -barWidth/2).
      attr("dy", "1.2em").
      attr("text-anchor", "middle").
      text(function(datum) { return datum.count;});

    languageBars.selectAll("text.yAxis").
      data(data).
      enter().append("svg:text").
      attr("x", function(datum, index) { return x(index) + barWidth; }).
      attr("y", height).
      attr("dx", -barWidth/2).
      attr("text-anchor", "middle").
      text(function(datum) { return datum.language;}).
      attr("transform", "translate(0, 18)").
      attr("class", "yAxis");
  </script>
</html>

唷! 同样,不必担心这段代码的主要功能。 这里值得注意的是顶行--var data = <%= languages %>;--它表示我们正在将先前创建的 languages 数组传递到 ERB 中进行处理。

如“D3 for Mortals(面向大众的 D3)”所述,这未必是 D3 的最佳用法。 但它确实表明了您能够如何配合使用该库与 Octokit,做出一些真正令人惊叹的事情。

结合不同的 API 调用

现在是时候坦白了:仓库中的 language 属性仅标识定义的“主要”语言。 这意味着,如果您的仓库结合了多种语言,则代码字节最多的语言将被视为主要语言。

让我们结合几个 API 调用来真正呈现哪种语言在我们所有代码中写入的字节数最多。 相比简单的计数,树形图应该是可视化编码语言使用量的好方法。 我们需要构造一个如下所示的对象数组:

[ { "name": "language1", "size": 100},
  { "name": "language2", "size": 23}
  ...
]

我们在前面已经获取了仓库列表,现在我们来检查每个仓库,然后调用语言列表 API 方法

repos.each do |repo|
  repo_name = repo.name
  repo_langs = octokit_client.languages("#{github_user.login}/#{repo_name}")
end

我们将从中找到的每种语言累加到“主列表”中:

repo_langs.each do |lang, count|
  if !language_obj[lang]
    language_obj[lang] = count
  else
    language_obj[lang] += count
  end
end

之后,我们将内容格式化为 D3 可以理解的结构:

language_obj.each do |lang, count|
  language_byte_count.push :name => "#{lang} (#{count})", :count => count
end

# some mandatory formatting for D3
language_bytes = [ :name => "language_bytes", :elements => language_byte_count]

(有关 D3 树图魔方的更多信息,请查看这个简单教程。)

最后,我们将这些 JSON 信息传递到同一个 ERB 模板:

erb :lang_freq, :locals => { :languages => languages.to_json, :language_byte_count => language_bytes.to_json}

与以前一样,这里有一堆 JavaScript,您可以直接将它们放到模板中:

<div id="byte_freq"></div>
<script>
  var language_bytes = <%= language_byte_count %>
  var childrenFunction = function(d){return d.elements};
  var sizeFunction = function(d){return d.count;};
  var colorFunction = function(d){return Math.floor(Math.random()*20)};
  var nameFunction = function(d){return d.name;};

  var color = d3.scale.linear()
              .domain([0,10,15,20])
              .range(["grey","green","yellow","red"]);

  drawTreemap(5000, 2000, '#byte_freq', language_bytes, childrenFunction, nameFunction, sizeFunction, colorFunction, color);

  function drawTreemap(height,width,elementSelector,language_bytes,childrenFunction,nameFunction,sizeFunction,colorFunction,colorScale){

      var treemap = d3.layout.treemap()
          .children(childrenFunction)
          .size([width,height])
          .value(sizeFunction);

      var div = d3.select(elementSelector)
          .append("div")
          .style("position","relative")
          .style("width",width + "px")
          .style("height",height + "px");

      div.data(language_bytes).selectAll("div")
          .data(function(d){return treemap.nodes(d);})
          .enter()
          .append("div")
          .attr("class","cell")
          .style("background",function(d){ return colorScale(colorFunction(d));})
          .call(cell)
          .text(nameFunction);
  }

  function cell(){
      this
          .style("left",function(d){return d.x + "px";})
          .style("top",function(d){return d.y + "px";})
          .style("width",function(d){return d.dx - 1 + "px";})
          .style("height",function(d){return d.dy - 1 + "px";});
  }
</script>

瞧! 包含仓库语言信息的精美矩形,按相对比例显示,让您一目了然。 您可能需要调整树形图的高度和宽度(作为前两个参数传递到上述 drawTreemap),使所有信息适当显示。

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。