updating the docs (#8)

* updated docs and added doc test to ci

* fixing ci

Author: timziebart

.travis.yml

@@ -27,12 +27,15 @@ matrix:
 #  apt: # apt-get for linux
 #    packages:
 #    - gfortran
-#before_script: # homebrew for mac
+before_script: # homebrew for mac
 #  - if [ $TRAVIS_OS_NAME = osx ]; then brew install gcc; fi
+  - julia -e 'using Pkg; Pkg.add(PackageSpec(name="Documenter", version="0.19"))'
 
 ## uncomment the following lines to override the default test script
-#script:
-#  - julia -e 'Pkg.clone(pwd()); Pkg.build("DPSABase"); Pkg.test("DPSABase"; coverage=true)'
+script:
+ # - julia -e 'Pkg.clone(pwd()); Pkg.build("DPSABase"); Pkg.test("DPSABase"; coverage=true)'
+ - julia --check-bounds=yes --color=yes -e "using Pkg; Pkg.test(coverage=true)"
+ - julia docs/make.jl
 after_success:
   # push coverage results to Coveralls
   # - julia -e 'cd(Pkg.dir("DPSABase")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'

docs/make.jl

@@ -7,4 +7,5 @@ makedocs(
     # html options
     format = :html,
     sitename = "PowerDynBase.jl",
-    pages = ["index.md"])
+    pages = ["index.md"],
+    strict=true)

src/DEVariables.jl

@@ -7,13 +7,33 @@ using MacroTools
 issymbol(::Symbol) = true
 issymbol(::Any) = false
 
-"Abstract super type for all variables that AbstractNodeDynamics sub types can be called with."
+"""
+    abstract type AbstractDEVariable end
+
+Abstract super type for all variables that [PowerDynBase.AbstractNetworkFunction`] sub-types can be called with.
+
+DEVariable stands for Differential Equation Variable.
+
+The basic idea of a DEVariable is to combine (the arrays of) all necessary variables for a sub-type of [`PowerDynBase.GridDynamics`].
+E.g. for a [`PowerDynBase.OrdinaryGridDynamics`] one needs only the state variable (here called `val` for value) and the derivative
+(here called `ddt`). Hence, the definition for the corresponding [`PowerDynBase.ODEVariable`] is:
+
+    @DEVariable struct ODEVariable{Tval, Tddt} <: AbstractODEVariable
+        val::AbstractVector{Tval}
+        ddt::AbstractVector{Tddt}
+    end ddt
+
+The final `ddt` statement is part of the [`PowerDynBase.@DEVariable`] macro stating that the output variable of this kind of DEVariable
+is `ddt`. Further, the [`PowerDynBase.@DEVariable`] macro generates all the necessary constructors. Check its docs for more details.
+"""
 abstract type AbstractDEVariable end
 
 """
     function mapfields(f, s, args...)
 
 Applies `f` to all fields of (the struct) `s` giving `args...` as additional arguments.
+
+It's written as a `@generated` function in order to ensure that the compiler can infer the types.
 """
 @generated function mapfields(f, s, args...)
     Expr(:call, nameof(s), [:(f(s.$field, args...)) for field in fieldnames(s) ]...)
@@ -24,7 +44,7 @@ function view(var::AbstractDEVariable, range)
     mapfields(view, var, range)
 end
 
-"Extend complexview from arrays to subtypes of [`AbstractDEVariable`](#ref)."
+"Extend [`PowerDynBase.complexview`] from arrays to subtypes of [`AbstractDEVariable`](#ref)."
 function complexview(var::AbstractDEVariable, i0, num)
     mapfields(complexview, var, i0, num)
 end
@@ -39,8 +59,8 @@ excomparison(exs) = Expr(:comparison, _excomparison(exs...)...)
 """
 Basically, this macro generates all the constructors (internal and external) for a subtype of AbstracDEVariable.
 
-If you really want to understand this macro, uncomment the `println(ex)` statement at the end and check the resulting
-generated expression.
+If you want to understand what this macro does, call [`PowerDynBase.showdefinition`](#ref) with a type that was generated by this macro, e.g.
+`showdefinition(ODEVariable)`. It will output the full defintion that the macro actually creates.
 """
 function create_DEVariable(structdef, outputfield::Symbol)
     structdef = deepcopy(structdef)
@@ -80,6 +100,19 @@ function create_DEVariable(structdef, outputfield::Symbol)
     ex
 end
 
+"""
+    @DEVariable struct DEVariableName{Type1, Type2, ...} <: AbstractODEVariable
+        ...
+    end outputVariableName
+
+Basically, this macro generates all the constructors (internal and external) for a subtype of AbstracDEVariable.
+In particular, it creates an external constructor that automatically chooses the type for the `outputVariableName` and instantiates this variable.
+
+If you want to understand what this macro does, call [`PowerDynBase.showdefinition`](#ref) with a type that was generated by this macro, e.g.
+`showdefinition(ODEVariable)`. It will output the full defintion that the macro actually creates.
+
+Furthermore, the macro is just the interface for the [`PowerDynBase.create_DEVariable`] function.
+"""
 macro DEVariable(structdef, outputfield)
     mainex = create_DEVariable(structdef, outputfield)
     @capture(structdef, struct name_{__} <: _

src/DynamicNodeMacro.jl

@@ -84,7 +84,7 @@ function getinternalvars(::Type{Val{T}}, args...;kwargs...) where {T}
     throw(NodeDynamicsError("unknown node dynamics type $T"))
 end
 
-"""See [`DPSABase.@DynamicNode`](#ref)."""
+"""See [`PowerDynBase.@DynamicNode`](#ref)."""
 function DynamicNode(typedef, prep, internalsdef, func_body)
     @capture(typedef, name_(parameters__) <: dynamicscall_)
     dynamicstype = dynamicscall.args[1]
@@ -172,5 +172,6 @@ macro DynamicNode(typedef, prep, internals, func_body)
     return esc(mainex)
 end
 
-"Show the definition generated by [`DPSABase.@DynamicNode`](#ref) for a subtype of [`AbstractNodeParameters`](#ref)."
+"Show the definition generated by a macro of PowerDynamics.jl,
+e.g. the macro [`PowerDynBase.@DynamicNode`](#ref) creting a subtype of [`PowerDynBase.AbstractNodeParameters`](#ref)."
 showdefinition(x) = showdefinition(stdout, x)

src/GridDynamics.jl

@@ -14,28 +14,58 @@ abstract type AbstractAlgebraicGridDynamics <: GridDynamics end
 
 NetworkRHS(g::GridDynamics) = g.rhs
 
-"TBD"
+"""
+    struct OrdinaryGridDynamics <: AbstractOrdinaryGridDynamics
+        rhs::NetworkRHS
+    end
+
+The data structure that contains all the information necessary for a power grid model that can be described
+as an ordinary differential equation. In this case, only the [`PowerDynBase.NetworkRHS`] is necessary.
+"""
 @with_kw struct OrdinaryGridDynamics <: AbstractOrdinaryGridDynamics
     rhs::NetworkRHS
 end
 (dyn::OrdinaryGridDynamics)(dx_dt::AbstractVector, x_in::AbstractVector, p, t) = dyn.rhs(ODEVariable(x_in, dx_dt), t)
 
-"TBD"
+"""
+    struct OrdinaryGridDynamicsWithMass <: AbstractAlgebraicGridDynamics
+        rhs::NetworkRHS
+        masses::AbstractVector{Bool} # diagonal part of the mass matrix, off-diagonal is assumed to be 0 anyway
+    end
+
+The data structure that contains all the information necessary for a power grid model that can be described
+as an ordinary differential equation with masses, i.e. a semi-explicit differential algebraic equation.
+`rhs` is the [`PowerDynBase.NetworkRHS`]. `masses` is a 1-dimensional array representing the diagonal entries
+of the mass matrix. The off-diagonal entries are assumed to be 0. `masses` can only contain boolean values
+representing: `true` the equation is treated as a ordinary differential eqation and `false` the equation is
+treated as an algebraic constraint on the state variables.
+"""
 @with_kw struct OrdinaryGridDynamicsWithMass <: AbstractAlgebraicGridDynamics
     rhs::NetworkRHS
     masses::AbstractVector{Bool} # diagonal part of the mass matrix, off-diagonal is assumed to be 0 anyway
 end
 (dyn::OrdinaryGridDynamicsWithMass)(dx_dt::AbstractVector, x_in::AbstractVector, p, t) = dyn.rhs(ODEVariable(x_in, dx_dt), t)
 
-"TBD"
+"""
+    struct AlgebraicGridDynamics <: AbstractAlgebraicGridDynamics
+        rhs::NetworkRHS
+        differentials::AbstractVector{Bool} # boolean values whether there a variable is a differential
+    end
+
+The data structure that contains all the information necessary for a power grid model that can be described
+as an differential algebraic equation.
+`rhs` is the [`PowerDynBase.NetworkRHS`]. `differentials` is a 1-dimensional array of boolean values.
+A `true` entry means the corresponding variable is dynamic and has a derivative variable.
+A `false` entry means the corresponding variable is defined by an algebraic constraint only.
+"""
 @with_kw struct AlgebraicGridDynamics <: AbstractAlgebraicGridDynamics
     rhs::NetworkRHS
     differentials::AbstractVector{Bool} # boolean values whether there a variable is a differential
 end
 (dyn::AlgebraicGridDynamics)(x_out::AbstractVector, dx_dt::AbstractVector, x_in::AbstractVector, p, t) = dyn.root(DAEVariable(val=x_in, ddt=dx_dt, out=x_out), t)
 
 
-"Create for each subtype of [`DPSABase.AbstractNodeDynamics`](#ref) the corresponding subtype of [`DPSABase.GridDynamics`](#ref)."
+"Create for each subtype of [`PowerDynBase.AbstractNodeDynamics`](#ref) the corresponding subtype of [`PowerDynBase.GridDynamics`](#ref)."
 _GridDynamics(nodes::AbstractVector{<:OrdinaryNodeDynamics}, LY::AbstractMatrix) =
     OrdinaryGridDynamics(NetworkRHS(nodes, LY))
 
@@ -63,9 +93,9 @@ end
         skip_LY_check=false,
         kwargs...)
 
-Bring all sutypes of [`DPSABase.AbstractNodeDynamics`](#ref) on one level and then
-create for each subtype of [`DPSABase.AbstractNodeDynamics`](#ref) the corresponding subtype of [`DPSABase.GridDynamics`](#ref) by using
-[`DPSABase._GridDynamics`](#ref).
+Bring all sutypes of [`PowerDynBase.AbstractNodeDynamics`](#ref) on one level and then
+create for each subtype of [`PowerDynBase.AbstractNodeDynamics`](#ref) the corresponding subtype of [`PowerDynBase.GridDynamics`](#ref) by using
+[`PowerDynBase._GridDynamics`](#ref).
 """
 function GridDynamics(
     nodes::AbstractArray{<:AbstractNodeDynamics},
@@ -84,16 +114,17 @@ end
 """
     function GridDynamics(nodes::AbstractVector{<:AbstractNodeParameters}, args...; kwargs...)
 
-Convert all subtypes of [`DPSABase.AbstractNodeParameters`](#ref) to the corresponding
-subtypes of [`DPSABase.AbstractNodeDynamics`](#ref) and then call [`DPSABase.GridDynamics`](#ref)
+Convert all subtypes of [`PowerDynBase.AbstractNodeParameters`](#ref) to the corresponding
+subtypes of [`PowerDynBase.AbstractNodeDynamics`](#ref) and then call [`PowerDynBase.GridDynamics`](#ref)
 again.
 """
 function GridDynamics(nodes::AbstractVector{<:AbstractNodeParameters}, args...; kwargs...)
     GridDynamics(map(construct_node_dynamics, nodes), args...; kwargs...)
 end
 
-
+"Return the 1-dimensional differentials array (see [`PowerDynBase.AlgebraicGridDynamics`]) for the internal variables for each node."
 int_differentials(node::AbstractAlgebraicNodeDynamics, nodes::AbstractAlgebraicNodeDynamics...) = [int_differentials(node); int_differentials(nodes...)]
+"Return the 1-dimensional differentials array (see [`PowerDynBase.AlgebraicGridDynamics`]) for the voltagee variables for each node."
 u_differentials(node::AbstractAlgebraicNodeDynamics, nodes::AbstractAlgebraicNodeDynamics...) = [u_differentials(node); u_differentials(nodes...)]
 u_differentials(node::OrdinaryNodeDynamicsWithMass) = repeat([node.m_u], inner=2) # 1 Complex number is 2 Real numbers
 int_differentials(node::OrdinaryNodeDynamicsWithMass) = node.m_int

src/NetwirkRHSs.jl

@@ -34,12 +34,9 @@ abstract type AbstractNetworkFunction{T<:AbstractNodeDynamics, M<:AbstractMatrix
         systemsize
         intrange # unitrange telling me where I find the internal dynamic variables
         nodalintranges # unit ranges to find the internal variables for each node in the full length of internal variables
-        rhsinterface::Function
     end
 
 Representing the full dynamics of the power grid.
-
-From [DPSABase.`AbstractNetworkFunction`](#ref) it inherits the conditions that `T<:AbstractNodeDynamics` and `M<:AbstractMatrix}`.
 """
 @with_kw struct NetworkRHS{T, M} <: AbstractNetworkFunction{T, M}
     nodes::AbstractVector{T}
@@ -49,12 +46,22 @@ From [DPSABase.`AbstractNetworkFunction`](#ref) it inherits the conditions that
     intrange # unitrange telling me where I find the internal dynamic variables
     nodalintranges # unit ranges to find the internal variables for each node in the full length of internal variables
 end
+"""
+    (rhs::NetworkRHS)(x::AbstractDEVariable, t)
+
+Evalate the network right-hand-side function.
+"""
 function (rhs::NetworkRHS)(x::AbstractDEVariable, t)
     # distribute the values of the of the DEVariables over all
     nodeiterator(rhs, x, t)
     nothing
 end
 # external constructor
+"""
+    NetworkRHS(nodes::AbstractVector{T}, LY::M) where {T<:AbstractNodeDynamics, M<:AbstractMatrix}
+
+Create an [`PowerDynBase.NetworkRHS`](#ref) object from a node list and the nodal admittance matrix.
+"""
 function NetworkRHS(nodes::AbstractVector{T}, LY::M) where {T<:AbstractNodeDynamics, M<:AbstractMatrix}
     numnodes = length(nodes)
     @assert size(LY) == (numnodes, numnodes)
@@ -68,14 +75,35 @@ function NetworkRHS(nodes::AbstractVector{T}, LY::M) where {T<:AbstractNodeDynam
         nodalintranges = internal_unitranges(nodes)
     )
 end
+
 Nodes(rhs::NetworkRHS) = rhs.nodes
 SystemSize(rhs::NetworkRHS) = rhs.systemsize
 AdmittanceLaplacian(rhs::NetworkRHS) = rhs.LY
 
 # fall-back: only GridDynamics(x) needs to be defined, the rest is automatically via this line and the following
+"""
+    NetworkRHS(x)
+
+Return the struct of type [`PowerDynBase.NetworkRHS`](#ref) for `x`.
+"""
 NetworkRHS(x) = x |> GridDynamics |> NetworkRHS
+"""
+    SystemSize(x)
+
+Return the full system size, i.e. number of independent, dynamic, real-valued variables, for `x`.
+"""
 SystemSize(x) = x |> NetworkRHS |> SystemSize
+"""
+    Nodes(x)
+
+Return the array of nodes for `x`.
+"""
 Nodes(x) = x |> NetworkRHS |> Nodes
+"""
+    AdmittanceLaplacian(x)
+
+Return the nodal admittance matrix of the system.
+"""
 AdmittanceLaplacian(x) = x |> NetworkRHS |> AdmittanceLaplacian
 
 """

src/NodeDynamicsBase.jl

@@ -73,8 +73,10 @@ getDEVariableType(::Type{Val{OrdinaryNodeDynamics}}) = ODEVariable
 "Get number of internal arguments of the node."
 nint(dyn::OrdinaryNodeDynamics) = dyn.n_int
 
+"Get the symbols data structure for the node."
 symbolsof(n::OrdinaryNodeDynamics) = n.symbols
 
+"Get the parameters struct for the node."
 parametersof(n::OrdinaryNodeDynamics) = n.parameters
 
 ################################################################################

src/NodeParametersBase.jl

@@ -20,9 +20,11 @@ struct ODENodeSymbols <: AbstractNodeSymbols
     vars::AbstractVector{Symbol}
     dvars::AbstractVector{Symbol}
 end
+"Get the symbols representing the internal variables of the node."
 internalsymbolsof(s::ODENodeSymbols) = s.vars
 internalsymbolsof(s::AbstractNodeSymbols) = s |> ODENodeSymbols |> internalsymbolsof
 internalsymbolsof(s) = s |> symbolsof |> internalsymbolsof
+"Get the symbols representing the derivative of the internal variables of the node."
 internaldsymbolsof(s::ODENodeSymbols) = s.dvars
 internaldsymbolsof(s::AbstractNodeSymbols) = s |> ODENodeSymbols |> internaldsymbolsof
 internaldsymbolsof(s) = s |> symbolsof |> internaldsymbolsof
@@ -33,6 +35,7 @@ struct DAENodeSymbols <: AbstractNodeSymbols
     DAENodeSymbols(vars, dvars, outvars) = new(ODENodeSymbols(vars, dvars), outvars)
 end
 ODENodeSymbols(s::DAENodeSymbols) = s.odesymbols
+"Get the symbols representing the output of the internal variables of the node."
 internaloutsymbolsof(s::DAENodeSymbols) = s.outvars
 internaloutsymbolsof(s::AbstractNodeSymbols) = s |> DAENodeSymbols |> internaloutsymbolsof
 internaloutsymbolsof(s) = s |> symbolsof |> internaloutsymbolsof

src/States.jl

@@ -25,7 +25,7 @@ Encode a state vector and the corresponding rhs information.
 # Indexing
 
 In an instance `b` of of a `BaseState` behaves like an
-[`Array`](@ref), i.e. you can access the ``j``-th element
+array, i.e. you can access the ``j``-th element
 of the state vector (and set it to a value ``ξ``) by calling `b[j] ( = ξ )`.
 
 """
@@ -67,9 +67,9 @@ Encode the information on the value of a state vector at a particular time point
 # Indexing
 
 Concerning the indexing, a `State` object ``s`` basically behaves like a
-an [`Array`](@ref).
+an array.
 There are plenty of convenient ways to access its contents at a node ``j``
-by using a particular [`Symbol`](@ref):
+by using a particular symbol:
 
 * `s[j, :u]`: complex voltage
 * `s[j, :v]`: voltage magnitude

src/complexview.jl

@@ -1,7 +1,13 @@
 # (C) 2018 Potsdam Institute for Climate Impact Research, authors and contributors (see AUTHORS file)
 # Licensed under GNU GPL v3 (see LICENSE file)
 
-"Interpret (part of) an array of real values as an array with complex values."
+"""
+    complexview(vec::AbstractArray, i0, n)
+
+Interpret (part of) an array of real values as an array with complex values.
+`i0` is the index where to start.
+`n` is the number of complex values that should be extracted.
+"""
 function complexview(vec::AbstractArray{T}, i0, n) where T
     vec_view = view(vec, i0:i0 + 2*n -1)
     reinterpret(Complex{T}, vec_view)