Roll out MLJ-compliant document strings for registered models

[ablaom]

After some preparation and discussion, I am announcing a new standard for MLJ model doc-strings, documented here. I believe detailed doc-strings can greatly improve the on-ramp for new MLJ users, but rolling them out across the MLJ ecosystem is a huge task. Please help if you can.

Here's the list:

• MLJLinearModels (@tlienart - ongoing) Includes Docs for L1+std MLJLinearModels.jl#117. PR pending: Create MLJ compliant doc strings MLJLinearModels.jl#138
• MLJGLMInterface (@josephsdavid)
• MLJMultivariateStatsInterface (@josephsdavid)
• EvoTrees (3rd party) (@jeremiedb)
• MLJClusteringInterface (@josephsdavid)
• MLJDecisionTreeInterface
• NearestNeighborModels @OkonSamuel
• MLJFlux (@josephsdavid)
• MLJLIBSVMInterface (Allow kernel to be callable, fix some sloppy implementation of the MLJ interface; add docstrings MLJLIBSVMInterface.jl#13) @ablaom
• MLJModels (Transformers.jl). All done but need to update OneHotEncoder to reflect Add missing value propagation to OneHotEncoder MLJModels.jl#457
• MLJModels (Constant.jl)
• MLJNaiveBayesInterface
• MLJTSVDInterface
• MLJText
• MLJXGBoostInterface (examples only)
• OutlierDetectionNeighbors (3rd party)
• OutlierDetectionNetworks (3rd party)
• OutlierDetectionPython (3rd party)
• ParallelKMeans (3rd party)
• PartialLeastSquaresRegressor (3rd party)
• BetaML (3rd party, separate MLJ model objects)
• LightGBM (3rd party)
• MLJScikitLearnInterface (see How do we include python documentation in doc-strings? MLJScikitLearnInterface.jl#37)

Assign yourself by adding your GH handle next the relevant package, or ping me below.

@jbrea @sjvollmer I understand you are using MLJ for teaching these days. Feel free to star (*) or otherwise indicate two or three priority packages (or better still, contribute a PR 😜 )

Procedure

Generally, the procedure for updating the document strings for a package looks like this:

• Bump the MLJModelInterface [compat] entry to "1.4", to make doc_header and the new human_name trait available, unless you have no plans to reference either.
• If model metadata (traits) is generated using metadata_model, then remove any descr or docstring kwargs (these two are synonyms) in the metadata_model call. If instead (and atypically) there is an explicit docstring trait declaration (as in MLJModelInterface.docstring(::Type{<:FunkyModel}) = "A funky model") then delete it.
• Move any existing doc-string for the type to the end of the file that defines the type, following it immediately with a restatement of the type name:

<used to be a doc-string here>
mutable struct FunkyType
    a::Int
end 

<lots of stuff, including metadata declarations>

# # DOCUMENT STRINGS 

"""
    FunkyModel(a=5)

Some stuff about FunkyModel

"""
FunkyModel

• Assimilate the content of the moved doc-string into a new compliant doc-string, with the help of an existing complaint doc-string you use as a template (classifiers and regressors, transformers).

• Check the docstring. If the programatically generated header reads strangely, add a human_name declaration (eg, in the metadata_model call).

[logankilpatrick]

@ablaom can you send me a link to where I can see all of the model documentation in its current form?

[ablaom]

Model-specific documentation is not currently collated. Part of the GSoD project is to create and organise such a collation. So I'd have to write a script that loads every model in the registry (about 200 models) and calls @doc on those types. But with the exception of those packages with ✔️ s above they're mostly empty or quite minimal. Do you want me to write this script? Perhaps you could say would exactly you want this for?

Regarding other documentation. We have a manual and this summary of other learning resources.

[logankilpatrick]

Great, the propsoal has been submitted and is available here: https://julialang.org/jsoc/gsod/2022/proposal/