Merge 53f3ef1 into 4e53a73

damphyr · Oct 5, 2018 · bd9d496 · bd9d496
2 parents 4e53a73 + 53f3ef1
commit bd9d496
Show file tree

Hide file tree

Showing 6 changed files with 90 additions and 24 deletions.
diff --git a/History.txt b/History.txt
@@ -1,14 +1,14 @@
-#1.1.0
-* Added task to create a graph of all available tasks as documentation
-* Fixed an infinite call stack when generating the docs and overriding the invoke method
+# 1.1.0
+ * Added task to create a graph of all available tasks as documentation (with colors)
+  * Using [ColorBrewer Set 1 of 9-class](http://colorbrewer2.org/#type=qualitative&scheme=Set1&n=9) for colours. Unfortunately no color-blind safe option for 9 classes available
 
 # 1.0.0
-* Major restructure.
-* Split the C/C++ build functionality off to a separate module. Gaudi core is now just the configuration loader and the build system placement conventions
-* Added task timing information to the core by monkey patching task invocation in rake.
-* Dropped support for Ruby 2.0 and 2.1, add 2.4 to the CI
-* Dropped automatic inclusion of custom module.
-* Dropped custom module altogether, folded functionality into gaudi-c
+ * Major restructure.
+ * Split the C/C++ build functionality off to a separate module. Gaudi core is now just the configuration loader and the build system placement conventions
+ * Added task timing information to the core by monkey patching task invocation in rake.
+ * Dropped support for Ruby 2.0 and 2.1, add 2.4 to the CI
+ * Dropped automatic inclusion of custom module.
+ * Dropped custom module altogether, folded functionality into gaudi-c
 
 # 0.12.1
  * Build configuration keys defined as lists (e.g. deps etc.) are now appendable (thanks to [MarkusPalcer](https://github.com/MarkusPalcer))

diff --git a/README.md b/README.md
@@ -20,21 +20,17 @@ Gaudi is meant to be a part of you code repository from the initial commit. To t
 
 Install the gaudi gem:
 
-```
-gem install gaudi
-```
+```gem install gaudi```
 
 Create the project scaffold:
 
-```
-gaudi -s gaudi_project
-```
+```gaudi -s gaudi_project```
+
+This will create a basic project structure and pull the current version of gaudi from the repo. The scaffold also adds the correct files and structure to support features like the [documentaiton tasks](doc/DOCUMENTATION.md)
 
 Add the gaudi-c module:
 
-```
-gaudi -l gaudi-c https://github.com/damphyr/gaudi.git gaudi_project
-```
+```gaudi -l gaudi-c https://github.com/damphyr/gaudi.git gaudi_project```
 
 ## Gaudi?
 
@@ -46,7 +42,7 @@ Gaudi was very much a builder and a craftsman, each of his buildings unique yet
 
 (The MIT License)
 
-Copyright (c) 2013-2017 Vassilis Rizopoulos
+Copyright (c) 2013-2018 Vassilis Rizopoulos
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

diff --git a/doc/BUILDSYSTEMS.md b/doc/BUILDSYSTEMS.md
@@ -24,7 +24,7 @@ It is meant to provide a consistent command line interface to every task and ope
 
 The underlying principles for such a system are [described elsewhere](ASPIRATIONS.md)
 
-The areas of responsibility for such a system can be categorized with labels like "build", "test", "deploy" but this becomes much easier if we color code it and add some pictures:
+The areas of responsibility for such a system can be categorized with labels like "build", "test", "deploy" but this becomes much easier if we colour code it and add some pictures:
 
 ![Areas of Responsibility](/doc/images/BuildSystem.png)
 

diff --git a/doc/DOCUMENTATION.md b/doc/DOCUMENTATION.md
@@ -0,0 +1,38 @@
+# gaudi documentation features
+
+## Gaudi library documentation
+
+```rake doc:gaudi```
+
+Since rake and gaudi is Ruby code there is a built-in facility for generating RDoc documentation.
+
+The `doc:gaudi` task will automatically generate the reference documentation for the build system code under `system_config.out/doc/gaudi`.
+
+It uses doc/BUILDSYSTEM.md as the main page, a file that is created when using the gaudi gem to scaffold a project.
+
+
+## Graphs
+
+Gaudi is meant to cover all responsibility areas of an extended build system (as [explained elsewhere](BUILDSYSTEMS.md)).
+
+![Areas of Responsibility](/doc/images/BuildSystem.png)
+
+On a mature system the number of tasks can quickly become overwhelming. To manage it better gaudi provides a task to create graphs (using the [graphviz dot format](http://www.graphviz.org/doc/info/lang.html) and the [graph](https://github.com/seattlerb/graph) gem)
+
+Use ```rake doc:graph:gaudi``` to create the diagram (as `system_config.out/doc/graphs/gaudi.png`).
+
+One organizational measure is to group tasks by namespace. If you use the following responsibility-to-namespace mapping you will get colours in the generated graph matching the colours in the overview image.
+
+|Area|Namespace|
+|----|----|
+|Generate|gen|
+|Build|build|
+|Static Analysis|lint|
+|Unit Testing|unit|
+|Package|pkg|
+|Deployment|deploy|
+|Test|test|
+
+In addition the `doc` namespace is assigned the brown variant in the colour scheme
+
+The colour pallete used is [Brewer scheme Set 1 of 9-class](http://colourbrewer2.org/#type=qualitative&scheme=Set1&n=9) 
diff --git a/doc/images/BuildSystem.png b/doc/images/BuildSystem.png
diff --git a/lib/gaudi/helpers/doc.rb b/lib/gaudi/helpers/doc.rb
@@ -1,16 +1,24 @@
 require 'graph'
 module Gaudi
   module Documentation
+    #Creates a .png with the dependency graph of all tasks detected by rake
+    #in system_config.out/graphs
+    #
+    #Note that tasks do not include file tasks (tasks associated with a file path)
+    #since these tend to be generated and flood the graph
     def task_graph system_config
       digraph do
         rotate
+        colorscheme(:set1, 9)
         node_attribs << filled
         task_graph_details()
-        mkdir_p(File.join(system_config.out_dir,'graphs'),:verbose=>false)
-        save File.join(system_config.out_dir,'graphs',"gaudi"), "png"
+        mkdir_p(File.join(system_config.out,'graphs'),:verbose=>false)
+        save File.join(system_config.out,'graphs',"gaudi"), "png"
       end#graph
     end
-
+    #:stopdoc:
+    #Iterate over all tasks building nodes, edges and an index of namespace->task name (where namespace only goes on level deep)
+    #Use the index to cluster and color the nodes
     def task_graph_details
       grouped_by_namespace={}
       no_filetasks=Rake::Task.tasks.select{|rt| rt.class==Rake::Task}
@@ -27,9 +35,33 @@ def task_graph_details
       end
       grouped_by_namespace.each do |k,v|
         cluster k do
-          v.each{|ar| node(ar)}
+          v.each{|ar| colored_node(ar,k)}
         end
       end
     end
+
+    def colored_node node_name,node_namespace
+      case node_namespace
+      when "gen"
+        c5<<node(node_name)
+      when "build"
+        c1<<node(node_name)
+      when "lint"
+        c3<<node(node_name)
+      when "unit"
+        c6<<node(node_name)
+      when "test"
+        c2<<node(node_name)
+      when "pkg"
+        c9<<node(node_name)
+      when "doc"
+        c7<<node(node_name)
+      when "deploy"
+        c8<<node(node_name)
+      else
+        node(node_name)
+      end
+    end
+    #:startdoc:
   end
 end