search

JuliaAI / MLJ.jl

A Julia machine learning framework
https://juliaai.github.io/MLJ.jl/
Other
1.79k stars 157 forks source link

Roll out MLJ-compliant document strings for registered models #913

Open ablaom opened 2 years ago

ablaom commented 2 years ago

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:

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:

<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
logankilpatrick commented 2 years ago

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

ablaom commented 2 years ago

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 commented 2 years ago

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