add doc_header utility for creating model docstring headers.

Author: ablaom

src/metadata_utils.jl

@@ -133,3 +133,36 @@ function metadata_model(
     end
     parentmodule(T).eval(ex)
 end
+
+function doc_header(model)
+    name = MLJModelInterface.name(model)
+    human_name = MLJModelInterface.human_name(model)
+    package_name = MLJModelInterface.package_name(model)
+    package_url = MLJModelInterface.package_url(model)
+    params = MLJModelInterface.hyperparameters(model)
+
+    ret =
+"""
+    $name
+
+Model type for $human_name, based on [$package_name]($package_url).
+
+From MLJ, the type can be imported using
+
+    $name = @load $name pkg=$package_name
+
+Construct an instance with default hyper-parameters using the syntax
+`model = $name()`.
+""" |> chomp
+
+    isempty(params) && return ret
+
+    p = first(params)
+    ret *=
+"""
+ Provide keyword arguments to override hyper-parameter defaults, as in
+`$name($p=...)`.
+""" |> chomp
+
+    return ret
+end

test/metadata_utils.jl

@@ -20,6 +20,14 @@ metadata_model(FooRegressor,
     target=AbstractVector{Continuous},
     descr="La di da")
 
+const HEADER = MLJModelInterface.doc_header(FooRegressor)
+
+@doc """
+$HEADER
+
+Yes, we have no bananas. We have no bananas today!
+""" FooRegressor
+
 @testset "metadata" begin
     setfull()
     M.implemented_methods(::FI, M::Type{<:MLJType}) =
@@ -47,3 +55,34 @@ metadata_model(FooRegressor,
     @test infos[:hyperparameter_types] == ("Int64", "Any")
     @test infos[:hyperparameter_ranges] == (nothing, nothing)
 end
+
+@testset "doc_header(model)" begin
+
+    # we test markdown parsed strings for less fussy comparison
+
+    header  = Markdown.parse(HEADER)
+    comparison =
+"""
+```
+FooRegressor
+```
+
+Model type for foo regressor, based on [FooRegressorPkg](http://existentialcomics.com/).
+
+From MLJ, the type can be imported using
+
+```
+FooRegressor = @load FooRegressor pkg=FooRegressorPkg
+```
+
+Construct an instance with default hyper-parameters using the syntax
+`model = FooRegressor()`. Provide keyword arguments to override hyper-parameter
+defaults, as in `FooRegressor(a=...)`.
+""" |> chomp |> Markdown.parse
+
+end
+
+@testset "document string" begin
+    doc = (@doc FooRegressor) |> string |> chomp
+    @test endswith(doc, "We have no bananas today!")
+end

test/runtests.jl

@@ -2,6 +2,7 @@ using Test, MLJModelInterface
 using ScientificTypesBase, ScientificTypes
 using Tables, Distances, CategoricalArrays, InteractiveUtils
 import DataFrames: DataFrame
+import Markdown
 
 const M  = MLJModelInterface
 const FI = M.FullInterface