Add some docs on pipeline items

README.md

@@ -5,7 +5,7 @@ Amazingly fast and highly customizable Git repository analysis engine written in
 Powered by [go-git](https://github.com/src-d/go-git) and [Babelfish](https://doc.bblf.sh).
 
 There are two tools: `hercules` and `labours.py`. The first is the program
-written in Go which takes a Git repository and runs a Directed Acyclic Graph (DAG) of analysis tasks.
+written in Go which takes a Git repository and runs a Directed Acyclic Graph (DAG) of [analysis tasks](doc/PIPELINE_ITEMS.md).
 The second is the Python script which draws some predefined plots. These two tools are normally used together through
 a pipe. It is possible to write custom analyses using the plugin system.
 

doc/PIPELINE_ITEMS.md

@@ -0,0 +1,47 @@
+Pipeline items
+==============
+
+### PipelineItem lifecycle
+
+```go
+type PipelineItem interface {
+	// Name returns the name of the analysis.
+	Name() string
+	// Provides returns the list of keys of reusable calculated entities.
+	// Other items may depend on them.
+	Provides() []string
+	// Requires returns the list of keys of needed entities which must be supplied in Consume().
+	Requires() []string
+	// ListConfigurationOptions returns the list of available options which can be consumed by Configure().
+	ListConfigurationOptions() []ConfigurationOption
+	// Configure performs the initial setup of the object by applying parameters from facts.
+	// It allows to create PipelineItems in a universal way.
+	Configure(facts map[string]interface{})
+	// Initialize prepares and resets the item. Consume() requires Initialize()
+	// to be called at least once beforehand.
+	Initialize(*git.Repository)
+	// Consume processes the next commit.
+	// deps contains the required entities which match Depends(). Besides, it always includes
+	// "commit" and "index".
+	// Returns the calculated entities which match Provides().
+	Consume(deps map[string]interface{}) (map[string]interface{}, error)
+}
+```
+
+![PipelineItem](pipeline_item.png)
+
+### LeafPipelineItem lifecycle
+
+```go
+type LeafPipelineItem interface {
+	PipelineItem
+	// Flag returns the cmdline name of the item.
+	Flag() string
+	// Finalize returns the result of the analysis.
+	Finalize() interface{}
+	// Serialize encodes the object returned by Finalize() to Text or Protocol Buffers.
+	Serialize(result interface{}, binary bool, writer io.Writer) error
+}
+```
+
+![LeafPipelineItem](leaf_pipeline_item.png)

doc/leaf_pipeline_item.dot

@@ -0,0 +1,28 @@
+digraph PipelineItem {
+  Name -> Registration
+  Provides -> Registration
+  Registration -> Resolution
+  Requires -> Resolution
+  Resolution -> Configure
+  Flag -> "Command Line"
+  ListConfigurationOptions -> "Command Line"
+  "Command Line" -> Configure
+  Configure -> Initialize
+  Repository -> Initialize
+  Initialize -> Consume
+  Commits -> Consume
+  Consume -> Consume
+  Consume -> Finalize
+  Finalize -> Result
+  Result -> Serialize
+  Serialize -> YAML
+  Serialize -> "Protocol Buffers"
+  Registration [style=filled, fillcolor=dimgray, fontcolor=white]
+  Resolution [style=filled, fillcolor=dimgray, fontcolor=white]
+  "Command Line" [style=filled, fillcolor=dimgray, fontcolor=white]
+  Repository [style=filled, fillcolor=gray]
+  Commits [style=filled, fillcolor=gray]
+  Result [style=filled, fillcolor=gray]
+  YAML [style=filled, fillcolor=gray]
+  "Protocol Buffers" [style=filled, fillcolor=gray]
+}

doc/pipeline_item.dot

@@ -0,0 +1,19 @@
+digraph PipelineItem {
+  Name -> Registration
+  Provides -> Registration
+  Registration -> Resolution
+  Requires -> Resolution
+  Resolution -> Configure
+  ListConfigurationOptions -> "Command Line"
+  "Command Line" -> Configure
+  Configure -> Initialize
+  Repository -> Initialize
+  Initialize -> Consume
+  Commits -> Consume
+  Consume -> Consume
+  Registration [style=filled, fillcolor=dimgray, fontcolor=white]
+  Resolution [style=filled, fillcolor=dimgray, fontcolor=white]
+  "Command Line" [style=filled, fillcolor=dimgray, fontcolor=white]
+  Repository [style=filled, fillcolor=gray]
+  Commits [style=filled, fillcolor=gray]
+}