Merge pull request #2346 from ven-k/vkb/icons-refactor

Improves `@icon` and adds related docs

Author: YingboMa

docs/src/basics/MTKModel_Connector.md

@@ -26,6 +26,7 @@ equations.
   - `@components`: for listing sub-components of the system
   - `@equations`: for the list of equations
   - `@extend`: for extending a base system and unpacking its states
+  - `@icon` : for embedding the model icon
   - `@parameters`: for specifying the symbolic parameters
   - `@structural_parameters`: for specifying non-symbolic parameters
   - `@variables`: for specifing the states
@@ -50,6 +51,7 @@ end
 end
 
 @mtkmodel ModelC begin
+    @icon "https://github.com/SciML/SciMLDocs/blob/main/docs/src/assets/logo.png"
     @structural_parameters begin
         f = sin
     end
@@ -58,6 +60,7 @@ end
     end
     @variables begin
         v(t) = v_var
+        v_array(t)[1:2, 1:3]
     end
     @extend ModelB(; p1)
     @components begin
@@ -69,6 +72,41 @@ end
 end
 ```
 
+#### `@icon`
+
+An icon can be embedded in 3 ways:
+
+  - URI
+  - Path to a valid image-file.<br>
+    It can be an absolute path. Or, a path relative to an icon directory; which is
+    `DEPOT_PATH[1]/mtk_icons` by default and can be changed by setting
+    `ENV["MTK_ICONS_DIR"]`.<br>
+    Internally, it is saved in the _File URI_ scheme.
+
+```julia
+@mtkmodel WithPathtoIcon begin
+    @icon "/home/user/.julia/dev/mtk_icons/icon.png"
+    # Rest of the model definition
+end
+```
+
+  - Inlined SVG.
+
+```julia
+@mtkmodel WithInlinedSVGIcon begin
+    @icon """<svg height="100" width="100">
+    <circle cx="50" cy="50" r="40" stroke="green" fill="none" stroke-width="3"/>
+    </svg>
+    """
+    # Rest of the model definition
+end
+```
+
+#### `@structural_parameters` begin block
+
+  - This block is for non symbolic input arguements. These are for inputs that usually are not meant to be part of components; but influence how they are defined. One can list inputs like boolean flags, functions etc... here.
+  - Whenever default values are specified, unlike parameters/variables, they are reflected in the keyword argument list.
+
 #### `@parameters` and `@variables` begin block
 
   - Parameters and variables are declared with respective begin blocks.
@@ -80,15 +118,10 @@ end
 ```julia
 julia> @mtkbuild model_c1 = ModelC(; v = 2.0);
 
-julia> ModelingToolkit.getdefault(model_c.v)
+julia> ModelingToolkit.getdefault(model_c1.v)
 2.0
 ```
 
-#### `@structural_parameters` begin block
-
-  - This block is for non symbolic input arguements. These are for inputs that usually are not meant to be part of components; but influence how they are defined. One can list inputs like boolean flags, functions etc... here.
-  - Whenever default values are specified, unlike parameters/variables, they are reflected in the keyword argument list.
-
 #### `@extend` begin block
 
   - Partial systems can be extended in a higher system as `@extend PartialSystem(; kwargs)`.
@@ -209,11 +242,12 @@ For example, the structure of `ModelC` is:
 
 ```julia
 julia> ModelC.structure
-Dict{Symbol, Any} with 6 entries:
+Dict{Symbol, Any} with 7 entries:
   :components           => [[:model_a, :ModelA]]
-  :variables            => Dict{Symbol, Dict{Symbol, Any}}(:v=>Dict(:default=>:v_var), :v_array=>Dict(:size=>(4,)))
+  :variables            => Dict{Symbol, Dict{Symbol, Any}}(:v=>Dict(:default=>:v_var), :v_array=>Dict(:size=>(2, 3)))
+  :icon                 => URI("https://github.com/SciML/SciMLDocs/blob/main/docs/src/assets/logo.png")
   :kwargs               => Dict{Symbol, Any}(:f=>:sin, :v=>:v_var, :v_array=>nothing, :model_a__k_array=>nothing, :p1=>nothing)
   :independent_variable => t
-  :extend               => Any[[:p1, :p2], :model_b, :ModelB]
-  :equations            => ["model_a.k1 ~ f(v)"]
+  :extend               => Any[[:p2, :p1], Symbol("#mtkmodel__anonymous__ModelB"), :ModelB]
+  :equations            => ["model_a.k ~ f(v)"]
 ```

src/systems/model_parsing.jl

@@ -259,7 +259,8 @@ function parse_model!(exprs, comps, ext, eqs, icon, vs, ps, sps,
     elseif mname == Symbol("@equations")
         parse_equations!(exprs, eqs, dict, body)
     elseif mname == Symbol("@icon")
-        parse_icon!(icon, dict, mod, body)
+        isassigned(icon) && error("This model has more than one icon.")
+        parse_icon!(icon, dict, body)
     else
         error("$mname is not handled.")
     end
@@ -471,7 +472,7 @@ function parse_equations!(exprs, eqs, dict, body)
     dict[:equations] = readable_code.(eqs)
 end
 
-function parse_icon!(icon, dict, mod, body::String)
+function parse_icon!(icon, dict, body::String)
     icon_dir = get(ENV, "MTK_ICONS_DIR", joinpath(DEPOT_PATH[1], "mtk_icons"))
     dict[:icon] = icon[] = if isfile(body)
         URI("file:///" * abspath(body))
@@ -483,17 +484,13 @@ function parse_icon!(icon, dict, mod, body::String)
         false
     end
         URI(body)
+    elseif (_body = lstrip(body); startswith(_body, r"<\?xml|<svg"))
+        String(_body) # With Julia-1.10 promoting `SubString{String}` to `String` can be dropped.
     else
-        error("$body is not a valid icon")
+        error("\n$body is not a valid icon")
     end
 end
 
-function parse_icon!(icon, dict, mod, body::Expr)
-    _icon = body.args[end]
-    dict[:icon] = icon[] = MLStyle.@match _icon begin
-        ::Symbol => get_var(mod, _icon)
-        ::String => _icon
-        Expr(:call, read, a...) => eval(_icon)
-        _ => error("$_icon isn't a valid icon")
-    end
+function parse_icon!(icon, dict, body::Expr)
+    parse_icon!(icon, dict, eval(body))
 end

test/icons/resistor.svg

@@ -62,9 +62,7 @@ end
     @components begin
         g = Pin()
     end
-    @icon begin
-        read(abspath(ENV["MTK_ICONS_DIR"], "ground.svg"), String)
-    end
+    @icon read(abspath(ENV["MTK_ICONS_DIR"], "ground.svg"), String)
     @equations begin
         g.v ~ 0
     end
@@ -76,10 +74,9 @@ resistor_log = "$(@__DIR__)/logo/resistor.svg"
     @parameters begin
         R, [unit = u"Ω"]
     end
-    @icon begin
-        """<?xml version="1.0" encoding="UTF-8"?>
+    @icon """<?xml version="1.0" encoding="UTF-8"?>
 <svg xmlns="http://www.w3.org/2000/svg" width="80" height="30">
-  <path d="M10 15
+<path d="M10 15
 l15 0
 l2.5 -5
 l5 10
@@ -91,7 +88,6 @@ l2.5 -5
 l15 0" stroke="black" stroke-width="1" stroke-linejoin="bevel" fill="none"></path>
 </svg>
 """
-    end
     @equations begin
         v ~ i * R
     end