Merge branch 'tools-to-build-doc-strings' into improved-doc-string-support

Author: ablaom

Project.toml

@@ -18,9 +18,10 @@ CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 ScientificTypes = "321657f4-b219-11e9-178b-2701a2544e81"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["CategoricalArrays", "DataFrames", "Distances", "InteractiveUtils", "ScientificTypes", "Tables", "Test"]
+test = ["CategoricalArrays", "DataFrames", "Distances", "InteractiveUtils", "Markdown", "ScientificTypes", "Tables", "Test"]

src/metadata_utils.jl

@@ -132,3 +132,103 @@ function metadata_model(
 
     parentmodule(T).eval(program)
 end
+
+# TODO: After `human_name` trait is added as model trait, include in
+# example given in the docstring for `doc_header`.
+
+"""
+    MLJModelInterface.doc_header(SomeModelType)
+
+Return a string suitable for interpolation in the document string of
+an MLJ model type. In the example given below, the header expands to
+something like this:
+
+>    `FooRegressor`
+>
+>Model type for foo regressor, based on [FooRegressorPkg.jl](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=...)`.
+
+Ordinarily, `doc_header` is used in document strings defined *after*
+the model type definition, as `doc_header` assumes model traits (in
+particular, `package_name` and `package_url`) to be defined; see also
+[`MLJModelInterface.metadata_pkg`](@ref).
+
+
+### Example
+
+Suppose a model type and traits have been defined by:
+
+```
+mutable struct FooRegressor
+    a::Int
+    b::Float64
+end
+
+metadata_pkg(FooRegressor,
+    name="FooRegressorPkg",
+    uuid="10745b16-79ce-11e8-11f9-7d13ad32a3b2",
+    url="http://existentialcomics.com/",
+    )
+metadata_model(FooRegressor,
+    input=Table(Continuous),
+    target=AbstractVector{Continuous},
+    descr="La di da")
+```
+
+Then the docstring is defined post-facto with the following code:
+
+```
+const HEADER = MLJModelInterface.doc_header(FooRegressor)
+
+@doc \"\"\"
+\$HEADER
+
+### Training data
+
+In MLJ or MLJBase, bind an instance `model` ...
+
+<rest of doc string goes here>
+
+\"\"\" FooRegressor
+```
+
+"""
+function doc_header(SomeModelType)
+    name = MLJModelInterface.name(SomeModelType)
+    human_name = MLJModelInterface.human_name(SomeModelType)
+    package_name = MLJModelInterface.package_name(SomeModelType)
+    package_url = MLJModelInterface.package_url(SomeModelType)
+    params = MLJModelInterface.hyperparameters(SomeModelType)
+
+    ret =
+"""
+    $name
+
+Model type for $human_name, based on [$(package_name).jl]($package_url).
+
+From MLJ, the type can be imported using
+
+    $name = @load $name pkg=$package_name
+
+Do `model = $name()` to construct an instance with default hyper-parameters.
+""" |> 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

@@ -32,6 +32,15 @@ metadata_model(FooRegressor,
                supports_class_weights=true,
                load_path="goo goo")
 
+const HEADER = MLJModelInterface.doc_header(FooRegressor)
+
+@doc """
+$HEADER
+
+Yes, we have no bananas. We have no bananas today!
+""" FooRegressor
+
+
 infos =  Dict(trait => eval(:(MLJModelInterface.$trait))(FooRegressor) for
               trait in M.MODEL_TRAITS)
 
@@ -59,3 +68,34 @@ infos =  Dict(trait => eval(:(MLJModelInterface.$trait))(FooRegressor) for
     @test infos[:hyperparameter_types] == ("Int64", "Any")
     @test infos[:hyperparameter_ranges] == (nothing, nothing)
 end
+
+@testset "doc_header(ModelType)" begin
+
+    # we test markdown parsed strings for less fussy comparison
+
+    header  = Markdown.parse(HEADER)
+    comparison =
+"""
+```
+FooRegressor
+```
+
+Model type for foo regressor, based on [FooRegressorPkg.jl](http://existentialcomics.com/).
+
+From MLJ, the type can be imported using
+
+```
+FooRegressor = @load FooRegressor pkg=FooRegressorPkg
+```
+
+Do `model = FooRegressor()` to construct an instance with default hyper-parameters.
+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