Merge pull request #57 from biaslab/doc-update

Documentation update. Version bumped to 0.10.0.

Project.toml

@@ -1,6 +1,6 @@
 name = "ForneyLab"
 uuid = "9fc3f58a-c2cc-5bff-9419-6a294fefdca9"
-version = "0.9.2"
+version = "0.10.0"
 
 [compat]
 julia = "≥ 0.7.0"

docs/make.jl

@@ -11,8 +11,8 @@ makedocs(modules = [ForneyLab],
         "Getting started" => "getting-started.md",
         "User guide" => "user-guide.md",
         "Library" => Any[
-            "Public API" => "library/public-api.md",
-            "Internal API" => "library/internal-api.md"
+            "User API" => "library/user-api.md",
+            "Developer API" => "library/developer-api.md"
         ],
         "Contributing" => "contributing.md",
         "Internals" => "internals.md"

docs/src/library/internal-api.md → docs/src/library/developer-api.md

@@ -1,26 +1,21 @@
-# Internal API
+# Developer API
 
-Documentation for `ForneyLab.jl`'s internal API.
+Documentation for `ForneyLab.jl`'s developer API.
 
 ## Contents
 ```@contents
-Pages = ["internal-api.md"]
+Pages = ["developer-api.md"]
 Depth = 5
 ```
 
 ## Index
 ```@index
 Modules = [ForneyLab]
-Pages = ["internal-api.md"]
+Pages = ["developer-api.md"]
 Order = [:macro, :module, :constant, :type, :function]
 ```
 
-## Extended factor nodes
-```@docs
-ForneyLab.@composite
-```
-
-## Extended rules
+## Extended rules registration
 ```@docs
 ForneyLab.@expectationPropagationRule
 ForneyLab.@marginalRule

docs/src/library/public-api.md → docs/src/library/user-api.md

@@ -1,19 +1,19 @@
 # User API
 
-Documentation for `ForneyLab.jl`'s public API.
+Documentation for `ForneyLab.jl`'s user API.
 
-See [Internal API](@ref) for internal package docs.
+If you want to know how you can extend `ForneyLab.jl` (e.g. register new update rules), see [Developer API](@ref).
 
 ## Contents
 ```@contents
-Pages = ["public-api.md"]
+Pages = ["user-api.md"]
 Depth = 5
 ```
 
 ## Index
 ```@index
 Modules = [ForneyLab]
-Pages = ["public-api.md"]
+Pages = ["user-api.md"]
 Order = [:macro, :module, :constant, :type, :function]
 ```
 

src/algorithms/expectation_propagation/expectation_propagation.jl

@@ -6,9 +6,10 @@ variationalExpectationPropagationSchedule,
 
 abstract type ExpectationPropagationRule{factor_type} <: MessageUpdateRule end
 
-"""
-expectationPropagationSchedule() generates a expectation propagation message passing schedule.
-"""
+""" 
+`expectationPropagationSchedule()` generates a expectation propagation
+message passing schedule. 
+""" 
 function expectationPropagationSchedule(variables::Vector{Variable})
     ep_sites = collectEPSites(nodes(current_graph))
     breaker_sites = Interface[site.partner for site in ep_sites]
@@ -30,7 +31,7 @@ function expectationPropagationSchedule(variables::Vector{Variable})
 end
 
 """
-variationalExpectationPropagationSchedule() generates an expectation propagation message passing schedule
+`variationalExpectationPropagationSchedule()` generates an expectation propagation message passing schedule
 that is limited to the `recognition_factor`. Updates on EP sites are computed with an `ExpectationPropagationRule`.
 """
 function variationalExpectationPropagationSchedule(recognition_factor::RecognitionFactor)
@@ -140,9 +141,9 @@ function collectInboundTypes(entry::ScheduleEntry,
 end
 
 """
-@expectationPropagationRule registers a expectation propagation update 
-rule by defining the rule type and the corresponding methods for the outboundType 
-and isApplicable functions. If no name (type) for the new rule is passed, a 
+`@expectationPropagationRule` registers a expectation propagation update 
+rule by defining the rule type and the corresponding methods for the `outboundType` 
+and `isApplicable` functions. If no name (type) for the new rule is passed, a 
 unique name (type) will be generated. Returns the rule type.
 """
 macro expectationPropagationRule(fields...)

src/algorithms/sum_product/sum_product.jl

@@ -5,10 +5,10 @@ sumProductSchedule,
 
 abstract type SumProductRule{factor_type} <: MessageUpdateRule end
 
-"""
-sumProductSchedule() generates a sum-product message passing schedule that computes the
-marginals for each of the argument variables.
-"""
+""" 
+`sumProductSchedule()` generates a sum-product message passing schedule that
+computes the marginals for each of the argument variables. 
+""" 
 function sumProductSchedule(variables::Vector{Variable})
     # Generate a feasible summary propagation schedule
     schedule = summaryPropagationSchedule(variables)
@@ -26,9 +26,9 @@ end
 sumProductSchedule(variable::Variable) = sumProductSchedule([variable])
 
 """
-internalSumProductSchedule() generates a sum-product message passing schedule
-for the inner graph of a CompositeNode. This schedule produces the sum-product
-message out of the specified outbound_interface.
+`internalSumProductSchedule()` generates a sum-product message passing schedule
+for the inner graph of a `CompositeNode`. This schedule produces the sum-product
+message out of the specified `outbound_interface`.
 """
 function internalSumProductSchedule(cnode::CompositeNode,
                                     outbound_interface::Interface,
@@ -120,10 +120,10 @@ function collectInboundTypes(entry::ScheduleEntry,
 end
 
 """
-@sumProductRule registers a sum-product update rule by defining the rule type
-and the corresponding methods for the outboundType and isApplicable functions.
-If no name (type) for the new rule is passed, a unique name (type) will be
-generated. Returns the rule type.
+`@sumProductRule` registers a sum-product update rule by defining the rule type
+and the corresponding methods for the `outboundType` and `isApplicable`
+functions. If no name (type) for the new rule is passed, a unique name (type)
+will be generated. Returns the rule type.
 """
 macro sumProductRule(fields...)
     # Init required fields in macro scope

src/algorithms/variational_bayes/joint_marginals.jl

@@ -3,13 +3,13 @@ MarginalRule,
 @marginalRule
 
 """
-MarginalRule{factor_type} specifies a joint marginal update rule with respect
+`MarginalRule{factor_type}` specifies a joint marginal update rule with respect
 to a node of type `factor_type`.
 """
 abstract type MarginalRule{factor_type} <: MarginalUpdateRule end
 
 """
-Construct a MarginalScheduleEntry for computing the marginal over `cluster`
+Construct a `MarginalScheduleEntry` for computing the marginal over `cluster`
 through a node-specific joint marginal update rule.
 """
 function MarginalScheduleEntry(cluster::Cluster, outbound_types::Dict{Interface, Type})
@@ -103,8 +103,8 @@ end
 marginalSchedule(q_factor::RecognitionFactor, schedule::Schedule) = marginalSchedule([q_factor], schedule)
 
 """
-@marginalRule registers a marginal update rule for a (joint) marginal
-by defining the rule type and the corresponding methods for the isApplicable functions.
+`@marginalRule` registers a marginal update rule for a (joint) marginal
+by defining the rule type and the corresponding methods for the `isApplicable` function.
 If no name (type) for the new rule is passed, a unique name (type) will be generated.
 Returns the rule type.
 """

src/algorithms/variational_bayes/naive_variational_bayes.jl

@@ -6,7 +6,7 @@ variationalSchedule,
 abstract type NaiveVariationalRule{factor_type} <: MessageUpdateRule end
 
 """
-variationalSchedule() generates a variational message passing schedule that computes the
+`variationalSchedule()` generates a variational message passing schedule that computes the
 marginals for each of the recognition distributions in the recognition factor.
 """
 function variationalSchedule(recognition_factors::Vector{RecognitionFactor})
@@ -86,12 +86,13 @@ function collectInboundTypes(   entry::ScheduleEntry,
     return inbound_types
 end
 
-"""
-@naiveVariationalRule registers a variational update rule for the naive (mean-field)
-factorization by defining the rule type and the corresponding methods for the 
-outboundType and isApplicable functions. If no name (type) for the new rule is
-passed, a unique name (type) will be generated. Returns the rule type.
-"""
+""" 
+`@naiveVariationalRule` registers a variational update rule for the naive
+(mean-field) factorization by defining the rule type and the corresponding
+methods for the `outboundType` and `isApplicable` functions. If no name (type)
+for the new rule is passed, a unique name (type) will be generated. Returns the
+rule type. 
+""" 
 macro naiveVariationalRule(fields...)
     # Init required fields in macro scope
     node_type = :unknown

src/algorithms/variational_bayes/recognition_factorization.jl

@@ -1,8 +1,8 @@
 export RecognitionFactor, RecognitionFactorization, currentRecognitionFactorization
 
 """
-A Cluster specifies a collection of `edges` adjacent to `node` that belong to the same
-RecognitionFactor. A joint marginal can be computed over a cluster.
+A `Cluster` specifies a collection of `edges` adjacent to `node` that belong to the same
+`RecognitionFactor`. A joint marginal can be computed over a cluster.
 """
 mutable struct Cluster <: AbstractCluster
     id::Symbol
@@ -19,7 +19,7 @@ end
 Base.isless(c1::Cluster, c2::Cluster) = isless("$(c1.id)", "$(c2.id)")
 
 """
-A RecognitionFactor specifies the subset of variables that comprise
+A `RecognitionFactor` specifies the subset of variables that comprise
 a joint factor in the recognition factorization.
 """
 mutable struct RecognitionFactor
@@ -138,7 +138,7 @@ end
 
 """
 Find the smallest legal subgraph that includes the argument edges. Default setting terminates the search at soft factors
-and does not constrain the search to a limiting set (as specified by an empty limit_set argument).
+and does not constrain the search to a limiting set (as specified by an empty `limit_set` argument).
 """
 function extend(edge_set::Set{Edge}; terminate_at_soft_factors=true, limit_set=Set{Edge}())
     cluster = Set{Edge}() # Set to fill with edges in cluster
@@ -164,7 +164,7 @@ end
 extend(edge::Edge; terminate_at_soft_factors=true, limit_set=Set{Edge}()) = extend(Set{Edge}([edge]), terminate_at_soft_factors=terminate_at_soft_factors, limit_set=limit_set)
 
 """
-A RecognitionFactorization holds a collection of (non-overlapping) recognition factors that
+A `RecognitionFactorization` holds a collection of (non-overlapping) recognition factors that
 specify the recognition factorization over a factor graph that is used for variational inference.
 """
 mutable struct RecognitionFactorization
@@ -177,7 +177,7 @@ mutable struct RecognitionFactorization
 end
 
 """
-Return currently active RecognitionFactorization.
+Return currently active `RecognitionFactorization`.
 Create one if there is none.
 """
 function currentRecognitionFactorization()
@@ -198,8 +198,8 @@ RecognitionFactorization() = setCurrentRecognitionFactorization(
         Dict{Tuple{FactorNode, Edge}, Symbol}()))
 
 """
-Construct a RecognitionFactorization consisting of one
-RecognitionFactor for each argument
+Construct a `RecognitionFactorization` consisting of one
+`RecognitionFactor` for each argument
 """
 function RecognitionFactorization(args::Vararg{Union{T, Set{T}, Vector{T}} where T<:Variable}; ids=Symbol[])
     rf = RecognitionFactorization()
@@ -215,7 +215,7 @@ function RecognitionFactorization(args::Vararg{Union{T, Set{T}, Vector{T}} where
 end
 
 """
-Return the id of the RecognitionFactor that `edge` belongs to
+Return the id of the `RecognitionFactor` that `edge` belongs to
 """
 function recognitionFactorId(edge::Edge)
     dict = current_recognition_factorization.edge_to_recognition_factor
@@ -253,7 +253,7 @@ Return the ids of the clusters/variables to which edges connected to `node` belo
 localClusterIds(node::FactorNode) = [clusterId(node, interface.edge) for interface in node.interfaces]
 
 """
-Return a dictionary from recognition factor-id to variable/cluster-ids local to node
+Return a dictionary from recognition factor-id to variable/cluster-ids local to `node`
 """
 function localRecognitionFactorization(node::FactorNode)
     # For each edge connected to node, collect the recognition factor and cluster id

src/algorithms/variational_bayes/structured_variational_bayes.jl

@@ -64,12 +64,13 @@ function collectInboundTypes(entry::ScheduleEntry,
     return inbound_types
 end
 
-"""
-@structuredVariationalRule registers a variational update rule for the structured
-factorization by defining the rule type and the corresponding methods for the 
-outboundType and isApplicable functions. If no name (type) for the new rule is
-passed, a unique name (type) will be generated. Returns the rule type.
-"""
+""" 
+`@structuredVariationalRule` registers a variational update rule for the
+structured factorization by defining the rule type and the corresponding methods
+for the `outboundType` and `isApplicable` functions. If no name (type) for the
+new rule is passed, a unique name (type) will be generated. Returns the rule
+type.
+""" 
 macro structuredVariationalRule(fields...)
     # Init required fields in macro scope
     node_type = :unknown

src/edge.jl

@@ -1,7 +1,7 @@
 export Edge
 
 """
-An Edge joins two interfaces (half-edges) `a` and `b`.
+An `Edge` joins two interfaces (half-edges) `a` and `b`.
 """
 mutable struct Edge <: AbstractEdge
     variable::AbstractVariable

src/factor_graph.jl

@@ -20,7 +20,7 @@ mutable struct FactorGraph
 end
 
 """
-Return currently active FactorGraph.
+Return currently active `FactorGraph`.
 Create one if there is none.
 """
 function currentGraph()

src/factor_nodes/bernoulli.jl

@@ -2,6 +2,7 @@ export Bernoulli
 
 """
 Description:
+
     Bernoulli factor node
 
     out ∈ {0, 1}
@@ -10,10 +11,12 @@ Description:
     f(out, p) = Ber(out|p) = p^out (1 - p)^{1 - out}
 
 Interfaces:
+
     1. out
     2. p
 
 Construction:
+
     Bernoulli(id=:some_id)
 """
 mutable struct Bernoulli <: SoftFactor

src/factor_nodes/beta.jl

@@ -2,6 +2,7 @@ export Beta
 
 """
 Description:
+
     Beta factor node
 
     Real scalars
@@ -11,11 +12,13 @@ Description:
     f(out, a, b) = Beta(out|a, b) = Γ(a + b)/(Γ(a) Γ(b)) out^{a - 1} (1 - out)^{b - 1}
 
 Interfaces:
+
     1. out
     2. a
     3. b
 
 Construction:
+
     Beta(id=:some_id)
 """
 mutable struct Beta <: SoftFactor

src/factor_nodes/categorical.jl

@@ -2,6 +2,7 @@ export Categorical
 
 """
 Description:
+
     Categorical factor node
 
     The categorical node defines a one-dimensional probability
@@ -14,10 +15,12 @@ Description:
               = Π_i p_i^{out_i}
 
 Interfaces:
+
     1. out
     2. p
 
 Construction:
+
     Categorical(id=:some_id)
 """
 mutable struct Categorical <: SoftFactor

src/factor_nodes/clamp.jl

@@ -52,7 +52,7 @@ function constant(value::Any; id=generateId(Clamp{variateType(value)}))
 end
 
 """
-@ensureVariables(...) casts all non-Variable arguments to Variable through constant(arg).
+`@ensureVariables(...)` casts all non-`Variable` arguments to `Variable` through constant(arg).
 """
 macro ensureVariables(args...)
     lines = ["isa($arg, Variable) || ($arg = constant($arg))" for arg in args]