gooddata 0.6.6 → 0.6.7

data/doc/pages/tutorial/CRUNCHING_NUMBERS.md

@@ -1,231 +0,0 @@
-# @title Crunching Numbers
-
-MAQL is a language that is fairly similar to SQL but it is aimed towards getting the data from OLAP system. You are never forced to talk about columns and specify joins explicitly. This is great but there are some drawbacks. Same as SQL MAQL is aimed towards users more than machines which does not help for automation but there is one more caveat that make it hard to use even for humans. Probably to your surprise
-
-    SELECT SUM(Amount)
-
-Is not a MAQL statement (even though you probably have seen this on UI). The more correct (and what goes back and forth over the wire) is
-
-    SELECT SUM([/gdc/md/132131231/obj/1])
-
-GoodData UI does a great job at hiding this complexity from you but this significantly hinders the use of MAQL over and API by regular Joes. Ruby SDK tries to alleviate the situation with some tricks. It also gives you many tools to programmatically define and deal with reports and lays the foundations for test driven BI.
-
-### Jack in
-If you do not have a project best would be to create one by following our tutorial [Your first project](http://sdk.gooddata.com/gooddata-ruby/recipe/2014/01/19/your-first-project.html) so you can get predictable results.
-
-First let's look around. There are no metrics
-
-	  GoodData::Metric[:all]
-	  > []
-
-there is one fact
-
-	  GoodData::Fact[:all]
-  	> [{"link"=>"/gdc/md/ptbedvc1841r4obgptywd2mzhbwjsfyr/obj/223",
-	    "author"=>"/gdc/account/profile/4e1e8cacc4989228e0ae531b30853248",
-	    "tags"=>"",
-	    "created"=>"2014-02-18 07:44:26",
-	    "deprecated"=>"0",
-	    "summary"=>"",
-	    "title"=>"Lines changed",
-	    "category"=>"fact",
-	    "updated"=>"2014-02-18 07:44:26",
-	    "contributor"=>"/gdc/account/profile/4e1e8cacc4989228e0ae531b30853248"}]
-
-### First metric
-Let's create our first metric. There are couple of ways so I will show them one by one. Regardless of how you create the metric the result is the same so pick the one that suits your style or situation.
-
-TBD(add identifier based metric)
-
-	  m = GoodData::Metric.create("SELECT SUM([/gdc/md/ptbedvc1841r4obgptywd2mzhbwjsfyr/obj/223])")
-
-You can do it like this but obviously this is the ugly verbose way.
-
-    m = GoodData::Metric.xcreate('SELECT SUM(#"Lines changed")')
-
-Here you are using the name of the fact. Let's notice couple of things. First we are not using create any more. Method xcreate stands for eXtended notation and tries to turn it into valid MAQL. When you are specifying the fact you are doing it using #"NAME".
-
-Regardless of which way you used you have a metric definition. Metric is only locally on your computer we haven't saved it yet. Let's do it.
-
-    m.save
-    > RuntimeError: Meric needs to have title
-
-Uh ok. You have two options
-
-    m.title = "My shiny metric"
-
-or
-
-    m = GoodData::Metric.xcreate(:title => "My shiny metric", :expression => 'SELECT SUM(#"Lines changed")')
-
-Go ahead and try saving it again.
-
-    m.save
-    > #<GoodData::Metric:0x007f95b609b548 ....
-
-Great, looks good. Let's see if it worked
-
-    m.saved?
-    > true
-
-    m.uri
-    > "/gdc/md/ptbedvc1841r4obgptywd2mzhbwjsfyr/obj/292"
-
-Let's get some numbers. You can execute the metric.
-
-    m.execute
-    > 9.0
-
-Fantastic. You just created your first report over API.
-
-### More on metric execution
-
-Maybe you are wondering if you cannot just execute stuff to poke around. Well you kinda can. The API does not allow to execute a metric without it is saved (but we hope this will change soon). SDK tries to hide this from you but sometimes you can see the wiring. Let's explore. This is our well known metric
-
-    m = GoodData::Metric.xcreate('SELECT SUM(#"Lines changed")')
-
-Let's try executing it
-
-    m.execute
-    > 9
-
-It works. What happens behind the scenes is that SDK saves the metric and then deletes it again. It should mostly work
-
-    m.is_saved?
-    > false
-
-    m.uri
-    > nil
-
-But sometimes you can see some inconsistencies.
-
-    m.title
-    > "Untitled metric"
-
-This should not stop you most of the time. Just keep this in mind. Hopefully it will go completely away soon.
-
-### Defining a ReportDefinition
-
-Ok we have our metric. Now it would be interesting to see a report. The metric broken down. If you are familiar with the model you know the metric is a summation of lines changed in all commits in all products made by all developers. Let's see, how developers contributed.
-
-    GoodData::ReportDefinition.execute(:top => ["attr.devs.id"], :left => [m])
-    > [ 1  |  2  |  3 ]
-      [1.0 | 3.0 | 5.0]
-
-Again, there are a lots of ways how to achieve the same result so let's have a look at what is available right now. You can already see that you can see a metric by reference and attribute can be referenced just by a string containing an identifier. Let's pass the attribute as an object as well.
-
-    a = GoodData::Attribute.get_by_id("attr.devs.id")
-    GoodData::ReportDefinition.execute(:top => [a], :left => [m])
-
-If you studied UI well you know that Report is defined using Display Forms (or labels) not by attribute. If you are specifying an attribute SDK will take the first one automatically. This works well most of the time since attributes have typically just one label. But sometimes they have many so you need to me more specific. Coincidently our attribute has 2 labels.
-
-    a.display_forms.count
-    > 2
-
-The identifiers are "label.devs.email" and "label.devs.id". Let's try using those
-
-    GoodData::ReportDefinition.execute(:top => ["label.devs.id"], :left => [m])
-    GoodData::ReportDefinition.execute(:top => ["label.devs.email"], :left => [m])
-
-You can even do something that you cannot do on UI and that is using both of the labels at the same time (sic).
-
-    GoodData::ReportDefinition.execute(:top => ["label.devs.id", "label.devs.email"], :left => [m])
-
-In almost all above cases we had only one thing in left or top section. You can save your fingers and not use the array literal if there is only one item in the section. SDK will wrap them for you.
-
-    GoodData::ReportDefinition.execute(:top => "label.devs.id", :left => m)
-
-Sometimes it might be useful to refer to the objects in a different way. You can do it by title
-
-    GoodData::ReportDefinition.execute(
-      :top => [{:type => :attribute, :title => "Month/Year (committed_on)"}],
-      :left => m)
-
-Since underneath it uses MdObject.find_first_by_title it also accepts RegExp literal
-
-    GoodData::ReportDefinition.execute(
-      :top => [{:type => :attribute, :title => /Month\/Year/}],
-      :left => m)
-
-    GoodData::ReportDefinition.execute(
-      :top => [{:type => :attribute, :title => /month\/year/i}],
-      :left => m)
-
-In our model we have two attributes of name Id. Since the title does not have to be unique this is ok. Currently it will pick the first for you but this behavior will likely change in the favor of throwing an ambiguous error much like your SQL client probably does.
-
-    GoodData::ReportDefinition.execute(:top => [{:type => :attribute, :title => "Id"}], :left => m)
-
-Of course you can combine all things we learned together.
-
-    a = GoodData::Attribute.find_first_by_title(/month\/year/i)
-    GoodData::ReportDefinition.execute(:top => [{:type => :attribute, :title => "Id"}], :left => [m, a])
-
-### Reports
-Up until now we have been computing the reports just because. Maybe you wonder how you can actually create a report that would be saved. It is simple
-
-    GoodData::ReportDefinition.execute(
-      :top => [{:type => :attribute, :title => /Month\/Year/}],
-      :left => m)
-
-    report = GoodData::Report.create(
-      :title => "Fantastic report",
-      :top => [{:type => :attribute, :title => /Month\/Year/}],
-      :left => m)
-
-    report.save
-
-### Results
-
-Ok now we know how to create a report. Now let's see what we can do with the result. The point of this framework is not only you being able to create reports programmatically and save them for consumption over UI. Yes this is incredibly useful but when we have that why stop there. With Ruby SDK  you can actually consume the result programmatically as well so you can use GD as a basis for your application. Or as we show in this section we build a foundation for Test Driven BI development.
-
-Let's execute one of the previously defined reports and this time let's store the result
-
-    result = GoodData::ReportDefinition.execute(
-      :top => [{:type => :attribute, :title => /month\/year/i}],
-      :left => m)
-    >
-    [Jan 2014 | Feb 2014]
-    [1.0      | 8.0     ]
-
-The class is ReportDataResult. As you will see further it tries to conform to API of an array in key aspoects
-
-    result.class
-    > GoodData::ReportDataResult
-
-    result[0][0]
-    > "Jan 2014"
-
-    result[1][0]
-    > 1.0
-
-All the numbers are of BigDecimal class so you should be able to perform additional computations without losing precision
-
-    result[1][0].class
-    > BigDecimal
-
-Let's look on couple of methods that are useful for validating the results of reports
-
-    result.include_row? [1, 8]
-    > true
-
-    result.include_column? ["Feb 2014", 8]
-    > true
-
-Result is coming from server in a special format but after some processing it is just an 2 D array so it is no wonder that you can test on equality of a whole report.
-
-    result == [["Jan 2014", "Feb 2014"], [1, 8]]
-
-<div class="section-nav">
-  <div class="left align-right">
-      <a href="/docs/file/doc/pages/tutorial/CREATING_A_MODEL.md" class="prev">
-        Back
-      </a>
-  </div>
-
-  <div class="right align-left">
-      <a href="/docs/file/doc/pages/tutorial/TEST_DRIVEN_DEVELOPMENT.md" class="next">
-        Next
-      </a>
-  </div>
-  <div class="clear"></div
-</div>

data/doc/pages/tutorial/TEST_DRIVEN_DEVELOPMENT.md

@@ -1,120 +0,0 @@
-# @title Test Driven Development
-
-Test driven development is a holy grail for many developers. It gives you an additional sense of security and you can rely on the test suite to give you a safety net when you are refactoring and tweaking existing code. Testing reports was hard until now.
-
-## The model
-Let's reuse the model that we have from model. Create a file called model.rb and put this inside.
-
-    GoodData::Model::ProjectBuilder.create("gooddata-ruby test #{Time.now.to_i}") do |p|
-      p.add_date_dimension("closed_date")
-
-      p.add_dataset("users") do |d|
-        d.add_anchor("id")
-        d.add_label("name", :reference => 'id')
-      end
-
-      p.add_dataset("regions") do |d|
-        d.add_anchor("id")
-        d.add_attribute("name")
-      end
-
-      p.add_dataset("opportunities") do |d|
-        d.add_fact("amount")
-        d.add_date("closed_date", :dataset => "closed_date")
-        d.add_reference("user_id", :dataset => 'users', :reference => 'id')
-        d.add_reference("region_id", :dataset => 'regions', :reference => 'id')
-      end
-
-      p.add_metric({
-        "title": "Sum Amount",
-        "expression": "SELECT SUM(#\"amount\") + 1",
-        "extended_notation": true
-      })
-
-      p.upload([["id", "name"],
-                ["1", "Tomas"],
-                ["2", "Petr"]], :dataset => 'users')
-
-      p.upload([["id", "name"],
-                ["1", "Tomas"],
-                ["2", "Petr"]], :dataset => 'regions')
-    end
-
-## The test
-Let's say that you have some not so simple metric and you want to test it so you make sure it works as expected. The easiest way to do it is create a testing project and prepare some made up data and then spin it. You already know how to create a model and load data let's talk about how to define test cases.
-
-The trick is to use assert_report helper. This means that the report will be executed and if the result will be different it will fail. The helper takes 2 parameters. First is a report definition second is the result expected. Currently it stops on the first failure but this will change soon and we will run all the tests and collect the results.
-
-    p.assert_report({:top => [{:type => :metric, :title => "Sum Amount"}]}, [["3"]])
-
-
-Go ahead and test it out
-
-    gooddata --username joe@example.com --password my_secret_pass --token my_token  project build model.rb
-
-
-## Production
-
-The way we have it set up right now nothing forces us to use the same metrics to build the report. This is a problem. Ideally we wanna make sure that the same report in test project is then used in production and if somebody changes the project because the business requirements changes we want the same report to be used in the test and if something fails we want to know.
-
-This is easiest to achieve by extracting the metrics and the model to separate file that can later be used when describing the project. You can then reference the same file form your production and testing project and make sure they are build using the same source.
-
-The description might look something like this
-
-    GoodData::Model::ProjectBuilder.create("gooddata-ruby test #{Time.now.to_i}") do |p|
-      p.add_date_dimension("closed_date")
-
-      p.add_dataset("users") do |d|
-        d.add_anchor("id")
-        d.add_label("name", :reference => 'id')
-      end
-
-      p.add_dataset("regions") do |d|
-        d.add_anchor("id")
-        d.add_attribute("name")
-      end
-
-      p.add_dataset("opportunities") do |d|
-        d.add_fact("amount")
-        d.add_date("closed_date", :dataset => "closed_date")
-        d.add_reference("user_id", :dataset => 'users', :reference => 'id')
-        d.add_reference("region_id", :dataset => 'regions', :reference => 'id')
-      end
-
-      p.load_metrics('https://bit.ly/gd_demo_1_metrics')
-
-      p.upload([["id", "name"],
-                ["1", "Tomas"],
-                ["2", "Petr"]], :dataset => 'users')
-
-      p.upload([["id", "name"],
-                ["1", "Tomas"],
-                ["2", "Petr"]], :dataset => 'regions')
-
-      p.upload([["amount", "closed_date", "user_id", "region_id"],
-                ["1", "2001/01/01", "1", "1"],
-                ["1", "2001/01/01", "1", "2"]], :dataset => 'opportunities')
-
-      p.assert_report({:top => [{:type => :metric, :title => "Sum Amount"}]}, [["3"]])
-
-    end
-
-Here we are externalizing only the metrics but you can hopefully see that it might make sense to do it for the model as well.
-
-# Rinse repeat
-If you have any experience with TDD you know that your tests have to run daily to have any effect. This is TBD :-)
-
-<div class="section-nav">
-  <div class="left align-right">
-      <a href="/docs/file/doc/pages/tutorial/CRUNCHING_NUMBERS.md" class="prev">
-        Back
-      </a>
-  </div>
-  <div class="right align-left">
-      <a href="/docs/file/doc/pages/tutorial/BRICKS.md" class="next">
-        Next
-      </a>
-  </div>
-  <div class="clear"></div>
-</div>
-

data/doc/pages/tutorial/YOUR_FIRST_PROJECT.md

@@ -1,53 +0,0 @@
-# @title Your First Project
-
-Ok welcome. Let's spin up an example project that we created so you can explore and see SDK in action. It is super simple. Since you are probably a developer we created simple project about developers.
-
-### What we want to measure
-Imagine you have a small dev shop. You have couple of developers. They crank out code. You also have couple of repositories for products. You want to measure how many lines of code each of the devs create. you wanna be able to track it by time by repository and by person. You want to see how many lines of code they committed.
-
-### Model
-This is how the model looks.
-
-![Model](https://dl.dropboxusercontent.com/s/1y97ziv5anmpn9s/gooddata_devs_demo_model.png?token_hash=AAENC89d8XOfCr9AnyQCrd9vwfhb-bDuYcORQ0AIRP2RQQ)
-
-### Spinning it up
-Let's do this. I assume you have gooddata SDK installed and working. Run
-
-    gooddata scaffold project my_test_project
-
-go to the directory
-
-    cd my_test_project
-
-and build project
-
-    gooddata -U username -P pass -t token project build
-
-If everything goes ok it will give you a PID also called a project_id. Open the my_test_project directory in your favorite text editor and open file called Goodfile. It should look like this
-
-    {
-      "model" : "./model/model.rb",
-      "project_id"   : ""
-    }
-
-Put your freshly acquired pid into an empty slot after "project_id". It should look like this.
-
-    {
-      "model" : "./model/model.rb",
-      "project_id"   : "HERE_COMES_YOUR NEW_TOKEN"
-    }
-
-You are done. If you go to [https://secure.gooddata.com/projects.html](https://secure.gooddata.com/projects.html) you should be able to see your new project. Also locally you are ready for other tutorials
-
-
-<div class="section-nav">
-    <div class="left align-right">
-        <span class="prev disabled">Back</span>
-    </div>
-
-    <div class="right align-left">
-        <a href="/docs/file/doc/pages/tutorial/CREATING_A_MODEL.md" class="next">Next</a>
-    </div>
-
-    <div class="clear"></div>
-</div>

data/doc/templates/default/class/dot/setup.rb

@@ -1,6 +0,0 @@
-include T('default/module/dot')
-
-def init
-  super
-  sections.push :superklass
-end

data/doc/templates/default/class/dot/superklass.erb

@@ -1,3 +0,0 @@
-<% if object.superclass.path != "Object" && object.superclass.path != "BasicObject" %>
-  <%= format_path object %> -> <%= format_path object.superclass %>;
-<% end %>

data/doc/templates/default/class/setup.rb

@@ -1,37 +0,0 @@
-include T('default/module')
-
-def init
-  super
-  sections.place(:subclasses).before(:children)
-  sections.place(:constructor_details, [T('method_details')]).before(:methodmissing)
-  sections.place(:specs).before(:children)
-end
-
-def constructor_details
-  ctors = object.meths(:inherited => true, :included => true)
-  return unless @ctor = ctors.find {|o| o.constructor? }
-  return if prune_method_listing([@ctor]).empty?
-  erb(:constructor_details)
-end
-
-def subclasses
-  return if object.path == "Object" # don't show subclasses for Object
-  unless globals.subclasses
-    globals.subclasses = {}
-    list = run_verifier Registry.all(:class)
-    list.each do |o|
-      (globals.subclasses[o.superclass.path] ||= []) << o if o.superclass
-    end
-  end
-
-  @subclasses = globals.subclasses[object.path]
-  return if @subclasses.nil? || @subclasses.empty?
-  @subclasses = @subclasses.sort_by {|o| o.path }.map do |child|
-    name = child.path
-    if object.namespace
-      name = object.relative_path(child)
-    end
-    [name, child]
-  end
-  erb(:subclasses)
-end