gooddata 0.6.0.pre9 → 0.6.0.pre10

data/doc/pages/tutorial/TEST_DRIVEN_DEVELOPMENT.md

@@ -0,0 +1,118 @@
+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

@@ -0,0 +1,52 @@
+
+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

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

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

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

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

@@ -0,0 +1,36 @@
+include T('default/module')
+
+def init
+  super
+  sections.place(:subclasses).before(:children)
+  sections.place(:constructor_details, [T('method_details')]).before(:methodmissing)
+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

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

@@ -0,0 +1,11 @@
+include T('default/module/text')
+
+def init
+  super
+  sections.place(:subclasses).before(:children)
+  sections.delete(:children)
+end
+
+def format_object_title(object)
+  "Class: #{object.title} < #{object.superclass.title}"
+end

data/doc/templates/default/class/text/subclasses.erb

@@ -0,0 +1,5 @@
+Direct Known Subclasses:
+------------------------
+
+<%= indent(wrap(@subclasses.map {|name, child| name }.join(", "))) %>
+

data/doc/templates/default/constant/text/header.erb

@@ -0,0 +1,11 @@
+<%= title_align_right format_object_title(object) %>
+
+
+<%= object.name %> = <%= object.value.size > 40 ? "\n\n" + indent(object.value) : object.value %>
+
+
+<%= hr %>
+
+<%= yieldall %>
+
+<%= hr %>

data/doc/templates/default/constant/text/setup.rb

@@ -0,0 +1,3 @@
+def init
+  sections :header, [T('docstring')]
+end

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

@@ -0,0 +1,51 @@
+def init
+  return if object.docstring.blank? && !object.has_tag?(:api)
+  sections :index, [:private, :deprecated, :abstract, :todo, :note, :returns_void, :text], T('tags')
+end
+
+def private
+  return unless object.has_tag?(:api) && object.tag(:api).text == 'private'
+  erb(:private)
+end
+
+def abstract
+  return unless object.has_tag?(:abstract)
+  erb(:abstract)
+end
+
+def deprecated
+  return unless object.has_tag?(:deprecated)
+  erb(:deprecated)
+end
+
+def todo
+  return unless object.has_tag?(:todo)
+  erb(:todo)
+end
+
+def note
+  return unless object.has_tag?(:note)
+  erb(:note)
+end
+
+def returns_void
+  return unless object.type == :method
+  return if object.name == :initialize && object.scope == :instance
+  return unless object.tags(:return).size == 1 && object.tag(:return).types == ['void']
+  erb(:returns_void)
+end
+
+def docstring_text
+  text = ""
+  unless object.tags(:overload).size == 1 && object.docstring.empty?
+    text = object.docstring
+  end
+
+  if text.strip.empty? && object.tags(:return).size == 1 && object.tag(:return).text
+    text = object.tag(:return).text.gsub(/\A([a-z])/) {|x| x.downcase }
+    text = "Returns #{text}" unless text.empty? || text =~ /^\s*return/i
+    text = text.gsub(/\A([a-z])/) {|x| x.upcase }
+  end
+
+  text.strip
+end

data/doc/templates/default/docstring/text/abstract.erb

@@ -0,0 +1,2 @@
+<%= indent(wrap("Abstract. #{object.tag(:abstract).text}")) %>
+

data/doc/templates/default/docstring/text/deprecated.erb

@@ -0,0 +1,2 @@
+<%= indent(wrap("Deprecated. #{object.tag(:deprecated).text}")) %>
+

data/doc/templates/default/docstring/text/index.erb

@@ -0,0 +1,2 @@
+
+<%= yieldall %>

data/doc/templates/default/docstring/text/note.erb

@@ -0,0 +1,4 @@
+<% object.tags(:note).each do |tag| %>
+<%= indent(wrap("Note: #{tag.text}")) %>
+
+<% end %>

data/doc/templates/default/docstring/text/private.erb

@@ -0,0 +1,2 @@
+<%= indent(wrap("This #{object.type} is part of a private API.")) %>
+

data/doc/templates/default/docstring/text/returns_void.erb

@@ -0,0 +1 @@
+<%= indent(wrap("This method returns an undefined value.")) %>

data/doc/templates/default/docstring/text/text.erb

@@ -0,0 +1 @@
+<%= indent wrap(h(docstring_text.strip), 68) %>

data/doc/templates/default/docstring/text/todo.erb

@@ -0,0 +1,4 @@
+<% object.tags(:todo).each do |tag| %>
+<%= indent(wrap("TODO: #{tag.text}")) %>
+
+<% end %>

data/doc/templates/default/layout/dot/header.erb

@@ -0,0 +1,6 @@
+digraph yard {
+  graph [rankdir=BT rank=sink outputMode=nodesfirst packMode="graph" splines=true];
+  node [shape=record rank=sink rankType=sink];
+
+  <%= yieldall %>
+}

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

@@ -0,0 +1,14 @@
+attr_reader :contents
+
+def init
+  if object
+    type = object.root? ? :module : object.type
+    sections :header, [T(type)]
+  else
+    sections :header, [:contents]
+  end
+end
+
+def header
+  tidy erb(:header)
+end

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

@@ -0,0 +1,3 @@
+def init
+  sections :header, [T('method_details')]
+end

data/doc/templates/default/method/text/header.erb

@@ -0,0 +1 @@
+<%= yieldall %>

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

@@ -0,0 +1,10 @@
+def init
+  sections :header, [:method_signature, T('docstring'), :source]
+end
+
+def source
+  return if owner != object.namespace
+  return if Tags::OverloadTag === object
+  return if object.source.nil?
+  erb(:source)
+end

data/doc/templates/default/method_details/text/header.erb

@@ -0,0 +1,10 @@
+<%= title_align_right format_object_title(object) %>
+
+<%= align_right "(Defined in: #{object.file})" %>
+<% if object.aliases.size > 0 %>
+
+<%= align_right "(Also known as: #{object.aliases.map {|o| o.name(true).to_s }.join(',')})" %>
+<% end %>
+
+<%= yieldall %>
+

data/doc/templates/default/method_details/text/method_signature.erb

@@ -0,0 +1,12 @@
+
+<% if object.tags(:overload).size == 1 %>
+<%= indent wrap(signature(object.tag(:overload))) %>
+<% elsif object.tags(:overload).size > 1 %>
+<% object.tags(:overload).each do |overload| %>
+<%= indent wrap(signature(overload)) %>
+<% end %>
+<% else %>
+<%= indent wrap(signature(object)) %>
+<% end %>
+<%= hr %>
+

data/doc/templates/default/method_details/text/setup.rb

@@ -0,0 +1,10 @@
+def init
+  super
+  sections.last.pop
+end
+
+def format_object_title(object)
+  title = "Method: #{object.name(true)}"
+  title += " (#{object.namespace})" if !object.namespace.root?
+  title
+end

data/doc/templates/default/module/dot/child.erb

@@ -0,0 +1 @@
+<%= format_path object %> [label="{<%= yieldall.gsub("\n", '') %>}" rank=sink];

data/doc/templates/default/module/dot/dependencies.erb

@@ -0,0 +1,3 @@
+<% object.mixins(:instance).each do |obj| %>
+  <%= format_path object %> -> <%= format_path obj %> [style=dotted arrowType=none];
+<% end %>

data/doc/templates/default/module/dot/header.erb

@@ -0,0 +1,6 @@
+subgraph cluster_<%= format_path object %> {
+  label = "<%= h(object.name) unless object.path == "" %>"; labelloc=b;
+  <% for obj in @modules %>
+    <%= yieldall :object => obj %>
+  <% end %>
+}

data/doc/templates/default/module/dot/info.erb

@@ -0,0 +1,14 @@
+<%= object.type %> <%= h object.name %>
+<% if options.full %>
+|
+<% object.attributes.each do |scope, list| %>
+<% list.sort_by {|name, rw| name.to_s }.each do |name, rw| %>
+<%= uml_visibility(rw.values.compact.first) %> <%= h (rw[:read]||rw[:write]).name(true).gsub(/=$/,'') %> [<%= 'R' if rw[:read] %><%= 'W' if rw[:write] %>]\l
+<% end %>
+<% end %>
+|
+<% method_listing.each do |obj| %>
+<%= uml_visibility obj %> <%= h obj.name(true) %>
+<%= h(" : #{obj.tag(:return).types.first}") if obj.has_tag?(:return) && obj.tag(:return).types && obj.tag(:return).types.size > 0 %>\l
+<% end %>
+<% end %>