Docstrings update (#11)

* DocStrings test code

* Add PARS and METHODS to Reaction docstrings

Uses PALEOboxes.DocStrings, which extends `DocStringExtensions` package

* Julia 1.6 compatibility fix (replace(...) only takes one pattern)

* another replace 1.6 compatibility fix

Co-authored-by: Stuart Daines <sd336@um-serve>

Project.toml

@@ -1,11 +1,12 @@
 name = "PALEOboxes"
 uuid = "804b410e-d900-4b2a-9ecd-f5a06d4c1fd4"
 authors = ["Stuart Daines <[email protected]>"]
-version = "0.16.0"
+version = "0.17.0"
 
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 Infiltrator = "5903a43b-9cc3-4c30-8d17-598619ec4e9b"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
@@ -27,6 +28,7 @@ YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 [compat]
 BenchmarkTools = "1.0"
 DataFrames = "1.1"
+DocStringExtensions = "0.8"
 Documenter = "0.27"
 Graphs = "1.4"
 Infiltrator = "1.0"

docs/src/CreateInitializeLoop.md

@@ -5,7 +5,7 @@ CurrentModule = PALEOboxes
 ```
 ## Model Creation
 
-A [YAML](https://en.wikipedia.org/wiki/YAML) format configuration file defines both the model structure (spatial domains containing biogeochemical variables and reactions that operate on them) and model parameter values. Reactions (subtypes of [`AbstractReaction`](@ref)) are registered in [`reaction_factories`](@ref) Dict and identified by name in the configuration file.
+A [YAML](https://en.wikipedia.org/wiki/YAML) format configuration file defines both the model structure (spatial domains containing biogeochemical variables and reactions that operate on them) and model parameter values. Reactions (subtypes of [`AbstractReaction`](@ref)) are identified by Type name (without module prefix) in the configuration file.
 
 To create the model, the numerical solver or host should call [`create_model_from_config`](@ref) which reads the configuration file, and then:
 - creates model [`Domain`](@ref)s and Reactions (subtypes of [`AbstractReaction`](@ref)), applying any [`Parameter`](@ref)s settings from the `parameters:` sections in the config file.

docs/src/Reaction API.md

@@ -30,6 +30,9 @@ setvalue!
 ## Registering with PALEOboxes framework
 ```@docs
 create_reaction(ReactionType::Type{<:AbstractReaction}, base::ReactionBase)
+
+find_reaction
+find_all_reactions
 ```
 
 ## Optional initialisation callbacks to define Domain Grids and array sizes

src/DocStrings.jl

@@ -0,0 +1,126 @@
+"""
+    DocStrings
+
+Extends Julia `DocStringExtensions` package to provide PALEO-specific "Abbreviations" to list 
+Reaction Parameters and Variables in docstrings.
+
+exports PARS, METHODS_SETUP, METHODS_INITIALIZE, METHODS_DO
+
+`\$(PARS)` expands to a list of Reaction Parameters
+`\$(METHODS_SETUP)`, `\$(METHODS_INITIALIZE)`, `\$(METHODS_DO)` expand to a list of ReactionMethods and Variables
+
+NB: a Reaction is created with `create_reaction`.  In addition, `\$(METHODS_DO)` etc call `register_methods(rj::AbstractReaction)`,
+so may fail if this call fails with default parameters.
+"""
+module DocStrings
+    import DocStringExtensions as DSE
+    import PALEOboxes as PB
+
+    struct Pars <: DSE.Abbreviation end
+
+    const PARS = Pars()
+
+    function DSE.format(::Pars, buf, doc)
+        local docs = get(doc.data, :fields, Dict())
+        local binding = doc.data[:binding]
+        local object = Docs.resolve(binding)
+
+        # println(buf, "PARS binding $binding object $object")
+
+        try
+            rj = PB.create_reaction(object, PB.ReactionBase(name="test", classname="test", external_parameters=Dict{String, Any}()))
+            if hasproperty(rj, :pars)
+                PB.add_par(rj, rj.pars)
+            end
+            # println(buf, "$object  $(length(PB.get_parameters(rj))) Parameters" )
+            for p in PB.get_parameters(rj)
+                md = "- `$(p.name)[$(typeof(p.v))]`="
+                md *= md_value(p.v)
+                md *= isempty(p.units) ? "," : "  ($(p.units)),"
+                md *= " `default_value`="*md_value(p.default_value)*","
+                md *= isempty(p.allowed_values) ? "" : " `allowed_values`=$(p.allowed_values),"
+                md *= " `description`=\"$(escape_md(p.description))\""
+                println(buf, md)
+            end
+        catch e
+            println(buf, escape_md("PARS exception: $e"))
+        end
+        return nothing
+    end
+
+    struct Methods <: DSE.Abbreviation
+        field::Symbol
+    end
+
+    const METHODS_SETUP = Methods(:methods_setup)
+    const METHODS_INITIALIZE = Methods(:methods_initialize)
+    const METHODS_DO = Methods(:methods_do)
+
+    function DSE.format(methods::Methods, buf, doc)
+        local docs = get(doc.data, :fields, Dict())
+        local binding = doc.data[:binding]
+        local object = Docs.resolve(binding)
+
+        try
+            # println(buf, "PARS binding $binding object $object")
+
+            rj = PB.create_reaction(object, PB.ReactionBase(name="test", classname="test", external_parameters=Dict{String, Any}()))
+            if hasproperty(rj, :pars)
+                PB.add_par(rj, rj.pars)
+            end
+
+            d = PB.Domain(name="test", ID=1, parameters=Dict{String, Any}())
+            rj.base.domain = d
+            PB.register_methods!(rj)
+
+            for m in getproperty(rj.base, methods.field)
+                println(buf, "- `$(m.name)`")
+                for v in PB.get_variables(m)
+                    md = "  - "
+                    md *= v.link_optional ? "\\[" : ""
+                    md *= "`$(v.localname)`"
+                    md *= v.link_optional ? "\\]" : ""
+                    ln = PB.combine_link_name(v)
+                    md *= (ln == v.localname) ? "" : " --> $(escape_md(ln))"
+                    units = PB.get_attribute(v, :units)
+                    md *= "  ($(units)),"
+                    md *= " `$(PB.get_var_type(v))`,"
+                    vfunction = PB.get_attribute(v, :vfunction)
+                    md *= (ismissing(vfunction) || vfunction == PB.VF_Undefined) ? "" : " `$vfunction`,"
+                    description = PB.get_attribute(v, :description)
+                    md *= " `description`=\"$(escape_md(description))\""
+
+                    println(buf, md)
+                end
+            end
+        catch e
+            println(buf, escape_md("METHODS $methods exception: $e"))
+        end
+
+        return nothing
+    end
+
+
+
+    function escape_md(str::AbstractString)
+        str = replace(str, "_"=>"\\_")
+        str = replace(str, "\$"=>"\\\$")
+        str = replace(str, "*"=>"\\*")
+        return str
+    end
+
+    md_value(v) = "$v"
+    md_value(v::AbstractString) = "\"$(escape_md(v))\""
+    function md_value(vv::Vector{<:AbstractString})
+        evv = [escape_md(v) for v in vv]
+        return "$evv"
+    end
+    function md_value(vv::Vector)
+        str = "$vv"
+        str = replace(str, "["=>"\\[")
+        str = replace(str, "]"=>"\\]")
+        return str
+    end
+
+    export PARS, METHODS_SETUP, METHODS_INITIALIZE, METHODS_DO
+end

src/PALEOboxes.jl

@@ -24,6 +24,8 @@ import YAML
 import Graphs # formerly LightGraphs
 import DataFrames
 
+include("DocStrings.jl")
+
 include("Types.jl")
 include("CoordsDims.jl")
 include("Fields.jl")

src/Reaction.jl

@@ -233,8 +233,8 @@ end
 
 Add a single parameter or parameters from fields of `objectwithpars` to a new Reaction.
 
-Not usually needed: [`add_reaction_factory`](@ref) will provide a [`reaction_factory`](@ref)
-that does this automatically for Parameters in pars::ParametersTuple.
+Not usually needed: Parameters in `pars::ParametersTuple`` will be added automatically, only needed if there are additional
+Parameters that are not members of `pars`.
 """
 function add_par(reaction::AbstractReaction, par::AbstractParameter)
 

src/ReactionFactory.jl

@@ -27,12 +27,30 @@ function find_all_reactions()
 
     for (rname, ReactionType) in duplicate_keys
         @warn "Duplicate reaction name $rname for Type $ReactionType (removing from Dict)"
-        delete!(rdict, rname)
+        if haskey(rdict, rname)
+            @warn "Duplicate reaction name $rname for Type $(rdict[rname]) (removing from Dict)"
+            delete!(rdict, rname)
+        end
     end
 
     return rdict
 end
 
+"""
+    find_reaction(class::AbstractString) -> ReactionType
+
+Look up "class" in list of Reactions from [`find_all_reactions`](@ref), and return 
+fully-qualified Reaction Type (including module prefixes).
+"""
+function find_reaction(class::AbstractString)
+    rdict = find_all_reactions()
+    if haskey(rdict, class)
+        return rdict[class]
+    else
+        error("class \"$class\" not found")
+    end
+end
+
 """
     create_reaction(ReactionType::Type{<:AbstractReaction}, base::ReactionBase) -> reaction::AbstractReaction
 
@@ -77,11 +95,11 @@ Examples:
 """
 function show_all_reactions(classnamefilter="", typenamefilter="")
 
-    for (classname, RType) in find_all_reactions()
+    for (classname, ReactionType) in find_all_reactions()
         if occursin(classnamefilter, classname)
             println(classname)
 
-            rtstring = Printf.@sprintf("%s", RType)
+            rtstring = Printf.@sprintf("%s", ReactionType)
             if  occursin(typenamefilter, rtstring )      
                 println("    ", RType)
 

src/reactioncatalog/FluxPerturb.jl

@@ -5,6 +5,8 @@ import Interpolations
 
 import PALEOboxes as PB
 
+using ..DocStrings
+
 """
     ReactionFluxPerturb
  
@@ -16,7 +18,13 @@ The input time Variable is `tforce`, with default linking to the `global.tforce`
 
 Use the configuration file to rename output variable `F` (and if necessary, the input Variable `tforce`).
 
-NB: no extrapolation ! (so eg set guard values for `force_times` at -1e30, 1e30)
+NB: no extrapolation ! (so eg set guard values for `perturb_times` at -1e30, 1e30)
+
+# Parameters
+$(PARS)
+
+# Methods and Variables
+$(METHODS_DO)
 """
 Base.@kwdef mutable struct ReactionFluxPerturb{P} <: PB.AbstractReaction
     base::PB.ReactionBase
@@ -108,6 +116,12 @@ end
     ReactionRestore
  
 Adds `RestoringFlux` in response to discrepancy between Variable `WatchLevel` and Parameter `RequiredLevel`
+
+# Parameters
+$(PARS)
+
+# Methods and Variables
+$(METHODS_DO)
 """
 Base.@kwdef mutable struct ReactionRestore{P} <: PB.AbstractReaction
     base::PB.ReactionBase

src/reactioncatalog/Fluxes.jl

@@ -41,6 +41,7 @@ import LinearAlgebra # for I
 
 import Infiltrator # Julia debugger
 
+using ..DocStrings
 """
     FluxContrib(
         fluxprefix::AbstractString, flux_list;
@@ -148,12 +149,17 @@ For each `fluxname` in `fluxlist`, creates:
   (or if `const_stub==true`, a constant `VarProp`).
 - if `flux_totals` is `true`, a total `VarPropScalar` `target_prefix.v*"flux_total_"*fluxname`.
 
+# Parameters
+$(PARS)
+
+# Methods and Variables for default Parameters
+$(METHODS_DO)
 """
 Base.@kwdef mutable struct ReactionFluxTarget{P} <: PB.AbstractReaction
     base::PB.ReactionBase
 
     pars::P = PB.ParametersTuple(
-        PB.ParStringVec("fluxlist", String[], 
+        PB.ParStringVec("fluxlist", ["example"], 
             description="available fluxes"),
 
         PB.ParString("target_prefix", "flux_",
@@ -231,27 +237,15 @@ end
 Copy fluxes, optionally using transfer matrices to define cell-cell mappings if input and output fluxes 
 are in a different Domain.
 
-A transfer is defined by Parameters:
-- `input_fluxes`: A list of input Variables generated by matches to string 
-  `[inputdomain.][inputsubdomain.]prefix\$fluxname\$suffix` where `\$fluxname\$` matches any string.
-  These have local names `input_\$fluxname\$`.
-- `output_fluxes`: Corresponding list of output Variables.
-  `[outputdomain.][outputsubdomain.]prefix\$fluxname\$suffix` where `\$fluxname\$` is generated from matches of `input_fluxes`.
-  These have local names `output_\$fluxname\$` and are optional (ie ignored if not linked). Usually the output Domain is the
-  Domain hosting the `ReactionFluxTransfer` (in general, it must be a Domain of the same size as the Domain hosting the
-  `ReactionFluxTransfer`).
-- `transfer_multiplier`: A scalar multiplier (usually 1.0).
-- `transfer_matrix`: Form of transfer matrix.
-  - 'Identity' copies fluxes directly assuming the output Domain has the same size as the input Domain.
-  - 'Distribute' uniformly distributes fluxes from input -> output, including common cases
-    n -> 1 (input flux is summed to a scalar output), 1 -> m (scalar input is distributed uniformly to m output cells).
-
 There are three common cases:
 - Transfer within a Domain, using `transfer_matrix` `Identity`
 - Transfer from a `fluxXXX` Domain to the Domain hosting the `ReactionFluxTransfer`, using `transfer_matrix` to
   define a mapping if these Domains are of different sizes.  
 - Transfer from a `fluxXXX` Domain to the boundary cells of an interior Domain (eg `ocean.oceansurface`), 
   where the Domain hosting the `ReactionFluxTransfer` is the corresponding boundary Domain (eg `oceansurface`).
+
+# Parameters
+$(PARS)
 """
 Base.@kwdef mutable struct ReactionFluxTransfer{P} <: PB.AbstractReaction
     base::PB.ReactionBase
@@ -260,20 +254,22 @@ Base.@kwdef mutable struct ReactionFluxTransfer{P} <: PB.AbstractReaction
         PB.ParStringVec("fluxlist", String[], 
             description="available fluxes"),
 
-        PB.ParString("input_fluxes", "domain.flux_\$fluxname\$",
-            description="string to match to find input flux Variables, 
-                will be linked to from local names \"input_<fluxname>\""),
-        PB.ParString("output_fluxes", "domain.subdomain.\$fluxname\$_sms", 
-            description="string to use to generate output flux Variables where \$fluxname\$ is substituted from input_fluxes, 
-            will be linked to from local names \"output_<fluxname>\""),
+        PB.ParString("input_fluxes", "[inputdomain.][inputsubdomain.]flux_\$fluxname\$",
+            description="string to match to find input flux Variables. "*
+                "These Variables will local names \"input_\$fluxname\$\"."),
+        PB.ParString("output_fluxes", "[outputdomain.][outputsubdomain.]\$fluxname\$_sms", 
+            description="string to use to generate output flux Variables where \$fluxname\$ is substituted from input_fluxes. "*
+                "These Variables will local names \"output_\$fluxname\$\", and are optional (ie ignored if not linked). "*
+                "Usually the output Domain is the Domain hosting the ReactionFluxTransfer (in general, it must be a Domain "*
+                "of the same size as the Domain hosting the ReactionFluxTransfer)."),
 
         PB.ParDouble("transfer_multiplier", 1.0, 
-            description="multiplier for transfer"),
+            description="scalar multiplier for transfer"),
         PB.ParString("transfer_matrix", "Identity", 
             allowed_values=["Identity", "Distribute", "Custom"],
             description="matrix defining input Domain (length n) -> output Domain (length m) mapping: 
-                'Identity' assumes m == n; 
-                'Distribute' sums over n and them distributes fraction 1/m evenly to each m;
+                'Identity' copies fluxes directly, requires m == n; 
+                'Distribute' uniformly distributes fluxes from input->output: sums over n and them distributes fraction 1/m evenly to each m;
                 'Custom' requires transfer matrix to be supplied"),
     )
 

src/reactioncatalog/Forcings.jl

@@ -2,6 +2,8 @@ module Forcings
 
 import PALEOboxes as PB
 
+using ..DocStrings
+
 """
     ReactionForceInterp
  
@@ -14,6 +16,12 @@ The input time Variable is `tforce`, with default linking to the `global.tforce`
 Use the configuration file to rename the output variable `F` (and if necessary, the input Variable `tforce`).
 
 NB: no extrapolation ! (so eg set guard values for `force_times` at -1e30, 1e30)
+
+# Parameters
+$(PARS)
+
+# Methods and Variables
+$(METHODS_DO)
  """
 Base.@kwdef mutable struct ReactionForceInterp{P} <: PB.AbstractReaction
     base::PB.ReactionBase