synthesize fallback for docstring() using other traits when no Base

Julia doc string

Author: ablaom

src/metadata_utils.jl

@@ -209,26 +209,71 @@ function doc_header(SomeModelType)
     params = MLJModelInterface.hyperparameters(SomeModelType)
 
     ret =
-"""
-    $name
+        """
+        ```
+        $name
+        ```
 
-Model type for $human_name, based on [$(package_name).jl]($package_url).
+        Model type for $human_name, based on [$(package_name).jl]($package_url).
 
-From MLJ, the type can be imported using
+        From MLJ, the type can be imported using
 
-    $name = @load $name pkg=$package_name
+        ```
+        $name = @load $name pkg=$package_name
+        ```
 
-Do `model = $name()` to construct an instance with default hyper-parameters.
-""" |> chomp
+        Do `model = $name()` to construct an instance with default hyper-parameters.
+        """ |> chomp
 
     isempty(params) && return ret
 
     p = first(params)
+    ret *= " "
     ret *=
+        """
+        Provide keyword arguments to override hyper-parameter defaults, as in
+        `$name($p=...)`.
+        """ |> chomp
+
+    return ret
+end
+
 """
- Provide keyword arguments to override hyper-parameter defaults, as in
-`$name($p=...)`.
-""" |> chomp
+    synthesize_docstring
+
+Private method.
+
+Generates a value for the `docstring` trait for use with a model which
+does not have a standard document string, to use as the fallback. See
+[`metadata_model`](@ref).
 
+"""
+function synthesize_docstring(M)
+    package_name = MLJModelInterface.package_name(M)
+    package_url  = MLJModelInterface.package_url(M)
+    model_name   = MLJModelInterface.name(M)
+    human_name   = MLJModelInterface.human_name(M)
+    hyperparameters = MLJModelInterface.hyperparameters(M)
+
+    # generate text for the section on hyperparameters
+    text_for_params = ""
+    if !is_wrapper(M)
+        model = M()
+        isempty(hyperparameters) || (text_for_params *= "### Hyper-parameters")
+        for p in hyperparameters
+            value = getproperty(model, p)
+            text_for_params *= "\n\n- `$p = $value`"
+        end
+    end
+
+    ret = doc_header(M)
+    if !isempty(text_for_params)
+        ret *=
+            """
+
+            $text_for_params
+
+            """
+    end
     return ret
 end

src/model_traits.jl

@@ -13,7 +13,13 @@ const DeterministicDetector = Union{
 
 const StatTraits = StatisticalTraits
 
-StatTraits.docstring(M::Type{<:Model}) = Base.Docs.doc(M) |> string
+function StatTraits.docstring(M::Type{<:Model})
+    docstring = Base.Docs.doc(M) |> string
+    if occursin("No documentation found", docstring)
+        docstring = synthesize_docstring(M)
+    end
+    return docstring
+end
 
 StatTraits.is_supervised(::Type{<:Supervised}) = true
 StatTraits.is_supervised(::Type{<:SupervisedAnnotator}) = true

test/model_traits.jl

@@ -2,6 +2,8 @@
 end
 
 @mlj_model mutable struct U1 <: Unsupervised
+    a::Int
+    b = sin
 end
 
 @mlj_model mutable struct D1 <: Deterministic
@@ -24,9 +26,17 @@ end
 foo(::P1) = 0
 bar(::P1) = nothing
 
+M.package_name(::Type{<:S1}) = "Sibelius"
+M.package_url(::Type{<:S1}) = "www.find_the_eighth.org"
+M.human_name(::Type{<:S1}) = "silly model"
+
+M.package_name(::Type{<:U1}) = "Bach"
+M.package_url(::Type{<:U1}) = "www.did_he_write_565.com"
+M.human_name(::Type{<:U1}) = "my model"
+
 @testset "traits" begin
     ms = S1()
-    mu = U1()
+    mu = U1(a=42, b=sin)
     md = D1()
     mp = P1()
     mi = I1()
@@ -38,11 +48,11 @@ bar(::P1) = nothing
     @test target_scitype(ms) == Unknown
     @test is_pure_julia(ms)  == false
 
-    @test package_name(ms) == "unknown"
+    @test package_name(ms) == "Sibelius"
     @test package_license(ms) == "unknown"
     @test load_path(ms) == "unknown"
     @test package_uuid(ms) == "unknown"
-    @test package_url(ms) == "unknown"
+    @test package_url(ms) == "www.find_the_eighth.org"
 
     @test is_wrapper(ms) == false
     @test supports_online(ms) == false
@@ -51,8 +61,38 @@ bar(::P1) = nothing
 
     @test hyperparameter_ranges(md) == (nothing,)
 
-    @test docstring(ms)[1:16] == "No documentation"[1:16]
+    @test docstring(ms) == M.doc_header(S1)
+    doc = docstring(mu) |> Markdown.parse
+    comparison =
+        """
+        ```
+        U1
+        ```
+
+        Model type for my model, based on [Bach.jl](www.did_he_write_565.com).
+
+        From MLJ, the type can be imported using
+
+        ```
+        U1 = @load U1 pkg=Bach
+        ```
+
+        Do `model = U1()` to construct an instance with default hyper-parameters.
+        Provide keyword arguments to override hyper-parameter defaults, as in
+        `U1(a=...)`.
+
+        ### Hyper-parameters
+
+        - `a = 0`
+
+        - `b = sin`
+
+        """ |> Markdown.parse
+    @test doc == comparison
+
     @test name(ms) == "S1"
+    @test human_name(ms) == "silly model"
+
 
     @test is_supervised(ms)
     @test is_supervised(sa)