add docs for interface

Author: hexaeder

docs/make.jl

@@ -11,7 +11,8 @@ makedocs(; modules=[NetworkLayout],
          sitename="NetworkLayout.jl",
          format=Documenter.HTML(; prettyurls=get(ENV, "CI", "false") == "true",
                                 canonical="https://juliagraphs.org/NetworkLayout.jl", assets=String[]),
-         pages=["Home" => "index.md",])
+         pages=["Home" => "index.md",
+                "Interface" => "interface.md"])
 
 # if gh_pages branch gets to big, check out
 # https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#gh-pages-Branch

docs/src/interface.md

@@ -0,0 +1,40 @@
+```@meta
+CurrentModule = NetworkLayout
+```
+
+# Layout Interface
+
+At its core, each layout algorithm is a mapping 
+```
+adj_matrix ↦ node_positions
+```
+where each algorithm has several parameters. The main goal of the following interface is to keep the separation between parameters and function call. 
+Each Algorithm is implemented as subtype of [`AbstractLayout`](@ref).
+
+```@docs
+AbstractLayout
+```
+
+Therefore, each `Algorithm <: AbstractLayout` is a functor and can be passed around as a function `adj_matrix ↦ node_positions` which encapsulates all the parameters. This is handy for plotting libraries such as [GraphMakie.jl](http://juliaplots.org/GraphMakie.jl/previews/PR9/).
+
+There are some additional guidelines:
+- All of the parameters should be keyword arguments, i.e. it should be allways
+  possible to call `Algorithm()` without specifying any parameters.
+- Algorithms should allways return `Vector{Point{dim,Ptype}}`. If the type or
+  dimensions can be altered use the keywords `dim` and `Ptype` for it.
+- Some parameters may depend on the specific network (i.e. length of start
+  positions vector). If possible, there should be a fallback option (i.e.
+  truncate the list of start positions if network is to small or append with
+  random values).
+
+## Iterative Layouts
+Iterative layouts are a specific type of layouts which produce a sequence of positions rather than a single list of positions. Those algorithms are implemented as subtypes of [`IterativeLayout`](@ref):
+
+```@docs
+IterativeLayout
+```
+
+One can instantiate an iterable object [`LayoutIterator`](@ref)
+```@docs
+LayoutIterator
+```

src/NetworkLayout.jl

@@ -5,15 +5,62 @@ export LayoutIterator, layout
 using GeometryBasics
 using LinearAlgebra: norm
 
+"""
+    abstract type AbstractLayout{Dim,Ptype} end
+
+Supertype for all layouts. Each layout `Algorithm <: AbstractLayout` needs to
+implement
+
+    layout(algo::Algorithm, adj_matrix)::Vector{Point{Dim,Ptype}}
+
+which takes the adjacency matrix representation of a network and returns a list of
+node positions. Each `Algorithm` object holds all of the necessary parameters.
+
+By implementing `layout` the algorithm also inherits the function-like property
+
+    Algorithm(; kwargs...)(adj_matrix) -> node_positions
+"""
 abstract type AbstractLayout{Dim,Ptype} end
 
 dim(::AbstractLayout{Dim,Ptype}) where {Dim,Ptype} = Dim
 ptype(::AbstractLayout{Dim,Ptype}) where {Dim,Ptype} = Ptype
 
 (lay::AbstractLayout)(adj_matrix) = layout(lay, adj_matrix)
 
+"""
+    abstract type IterativeLayout{Dim,Ptype} <: AbstractLayout{Dim,Ptype} end
+
+Supertype for iterative layouts. Instead of implementing `layout` directly,
+subtypes `Algorithm<:IterativeLayout` need to implement the [iterator
+interface](https://docs.julialang.org/en/v1/manual/interfaces/#man-interface-iteration)
+
+    Base.iterate(iter::LayoutIterator{<:Algorithm})
+    Base.iterate(iter::LayoutIterator{<:Algorithm}, state)
+
+where the iteration _item_ is a `Vector{Point{Dim,Ptype}}` and the iteration
+_state_ depends on the algorithm.
+
+By implementing the iterator interface the `Algorithm` inherits the `layout` and
+function-like call
+
+    layout(algo::Algorithm, adj_matrix) -> node_postions
+    Algorithm(; kwargs...)(adj_matrix) -> node_positions
+"""
 abstract type IterativeLayout{Dim,Ptype} <: AbstractLayout{Dim,Ptype} end
 
+"""
+    LayoutIterator(algorithm::IterativeLayout, adj_matrix)
+
+This type bundles an [`IterativeLayout`](@ref) with an adjacency matrix to form an
+iterable object whose items are the node positions.
+
+## Example
+```
+for p in LayoutIterator(Stress(), adj_matrix)
+    # do stuff with positions p
+end
+```
+"""
 struct LayoutIterator{T<:IterativeLayout,M<:AbstractMatrix}
     algorithm::T
     adj_matrix::M