Merge pull request #916 from alan-turing-institute/dev

Documentation update. No new release.

docs/make.jl

@@ -30,6 +30,7 @@ const MMI = MLJModelInterface
 pages = [
     "Home" => "index.md",
     "About MLJ" => "about_mlj.md",
+    "Learning MLJ" => "learning_mlj.md",
     "Getting Started" => "getting_started.md",
     "Common MLJ Workflows" => "common_mlj_workflows.md",
     "Working with Categorical Data" => "working_with_categorical_data.md",

docs/src/about_mlj.md

@@ -2,7 +2,7 @@
 
 MLJ (Machine Learning in Julia) is a toolbox written in Julia
 providing a common interface and meta-algorithms for selecting,
-tuning, evaluating, composing and comparing [over 150 machine learning
+tuning, evaluating, composing and comparing [over 180 machine learning
 models](@ref model_list) written in Julia and other languages. In
 particular MLJ wraps a large number of
 [scikit-learn](https://scikit-learn.org/stable/) models.
@@ -11,8 +11,7 @@ MLJ is released under the MIT licensed.
 
 ## Lightning tour
 
-*For more elementary introductions to MLJ usage see [Basic
-introductions](@ref) below.*
+*For help learning to use MLJ, see [Learning MLJ](@ref)*.
 
 A self-contained notebook and julia script of this demonstration is
 also available
@@ -218,6 +217,9 @@ on the `#mlj` slack workspace in the Julia Slack channel.
 Bugs, suggestions, and feature requests can be posted
 [here](https://github.com/alan-turing-institute/MLJ.jl/issues).
 
+Users are also welcome to join the `#mlj` Julia slack channel to ask
+questions and make suggestions.
+
 See also, [Known Issues](@ref)
 
 
@@ -273,40 +275,6 @@ install directly. Developers can learn more about these
 See also the alternative instalation instructions for [Modifying Behavior](@ref).
 
 
-## Learning Julia
-
-If you have experience in programming in another language but are new
-to Julia, then we highly recommend Aaron Christinson's tutorial
-[Dispatching Design
-Patterns](https://github.com/ninjaaron/dispatching-design-patterns)
-which is nicely compressed in his [half-hour
-video presentation](https://www.youtube.com/watch?v=n-E-1-A_rZM).
-
-However, one doesn't need to be able to program in Julia to start
-using MLJ.
-
-## Learning to use MLJ
-
-The present document, although littered with examples, is primarily
-intended as a complete reference. Resources for learning MLJ are:
-
-### Basic introductions
-
-- the [Getting Started](@ref) section of this manual
-
-To get direct help from maintainers and other users, see [Getting help
-and reporting problems](@ref).
-
-
-### In depth
-
-- the MLJ JuliaCon2020 Workshop [materials](https://github.com/ablaom/MachineLearningInJulia2020) and [video recording](https://www.youtube.com/watch?time_continue=27&v=qSWbCn170HU&feature=emb_title)
-
-- [Data Science Tutorials in Julia](https://alan-turing-institute.github.io/DataScienceTutorials.jl/)
-
-Users are also welcome to join the `#mlj` Julia slack channel to ask
-questions and make suggestions.
-
 ## Funding
 
 MLJ was initially created as a Tools, Practices and Systems project at

docs/src/getting_started.md

@@ -3,9 +3,9 @@
 For an outline of MLJ's **goals** and **features**, see
 [About MLJ](@ref).
 
-This section introduces the most basic MLJ operations and concepts. It
-assumes MJL has been successfully installed. See [Installation](@ref)
-if this is not the case.
+This section introduces only the most basic MLJ operations and
+concepts. It assumes MJL has been successfully installed. See
+[Installation](@ref) if this is not the case. 
 
 
 ```@setup doda

docs/src/index.md

@@ -6,8 +6,7 @@
     style="color: #389826;">About</a>           &nbsp;|&nbsp;
   <a href="https://alan-turing-institute.github.io/MLJ.jl/dev/about_mlj/#Installation" 
     style="color: #389826;">Install</a>         &nbsp;|&nbsp;
-  <a href="https://alan-turing-institute.github.io/MLJ.jl/dev/about_mlj/#Learning-to-use-MLJ"
-    style="color: #389826;">Learn</a>    &nbsp;|&nbsp;
+  <a href="learning_mlj"   style="color: #389826;">Learn</a>            &nbsp;|&nbsp;
   <a href="mlj_cheatsheet" style="color: #9558B2;">Cheatsheet</a>       &nbsp;|&nbsp;
   <a href="common_mlj_workflows" style="color: #9558B2;">Workflows</a>  &nbsp;|&nbsp;
   <a href="https://github.com/alan-turing-institute/MLJ.jl/" style="color: #9558B2;">For Developers</a> &nbsp;|&nbsp;

docs/src/learning_mlj.md

@@ -0,0 +1,60 @@
+# Learning MLJ
+
+[MLJ Cheatsheet](@ref)
+
+See also [Getting help and reporting problems](@ref).
+
+The present document, although littered with examples, is primarily
+intended as a complete reference. 
+
+#### New to machine learning?
+
+Try the "Introduction to Statistical
+Learning" notebooks at [Data Science
+Tutorials](https://juliaai.github.io/DataScienceTutorials.jl/),
+starting with [this
+tutorial](https://juliaai.github.io/DataScienceTutorials.jl/isl/lab-2/).
+Or have a look at the [Julia Data
+Science](https://github.com/JuliaDataScience/JuliaDataScience) book.
+
+#### Know a little machine learning and just want some MLJ basics?
+
+Read [Getting Started](@ref).
+
+#### A practicing data scientist transitioning from another platform?
+
+If, for example, you're coming from scikit-learn or R, we recommend
+your start with [MLJ for Data Scientists in Two
+Hours](https://github.com/alan-turing-institute/MLJ.jl/blob/dev/examples/telco/notebook.ipynb).
+
+#### Want a compressed survey of key MLJ functionality?
+
+Try this [Lightning
+Tour](https://github.com/alan-turing-institute/MLJ.jl/blob/dev/examples/lightning_tour/lightning_tour.ipynb).
+
+#### Something more leisurely?
+
+See
+[MLJTutorial](https://github.com/ablaom/MLJTutorial.jl).
+
+#### Prefer a video resource?
+
+Try the slightly older [MLJ JuliaCon2020
+Workshop](https://github.com/ablaom/MachineLearningInJulia2020)
+version of preceding resource, and accompanying [video
+recording](https://www.youtube.com/watch?time_continue=27&v=qSWbCn170HU&feature=emb_title).
+
+#### Looking for more end-to-end examples?
+
+Browse [Data Science
+Tutorials](https://juliaai.github.io/DataScienceTutorials.jl).
+
+#### Power MLJ user seeking to wrap complicated workflows?
+
+Learn about [Learning Networks](@ref).
+
+#### Completely new to Julia?
+
+Browse [these resources](https://julialang.org/learning/) or visit
+[HelloJulia](https://github.com/ablaom/HelloJulia.jl).
+

docs/src/mlj_cheatsheet.md

@@ -15,6 +15,9 @@ MLJ_VERSION # version of MLJ for this cheatsheet
 `info("RidgeRegressor", pkg="MultivariateStats")` retrieves metadata
 for "RidgeRegresssor", which is provided by multiple packages
 
+`doc("DecisionTreeClassifier", pkg="DecisionTree")` retrieves the
+model document string for the classifier, without loading model code
+
 `models()` lists metadata of every registered model.
 
 `models("Tree")` lists models with "Tree" in the model or package name.

docs/src/model_search.md

@@ -33,8 +33,14 @@ info("PCA")
 So a "model" in the present context is just a named tuple containing
 metadata, and not an actual model type or instance. If two models with
 the same name occur in different packages, the package name must be
-specified, as in `info("LinearRegressor", pkg="GLM")`.
+specified, as in `info("LinearRegressor", pkg="GLM")`. 
 
+Model document strings can be retreived, without importing the
+defining code, using the `doc` function:
+
+```
+doc("DecisionTreeClassifier", pkg="DecisionTree")
+```
 
 ## General model queries
 

examples/generate.jl

@@ -0,0 +1,39 @@
+# helper
+function runcommand(cmd)
+    @info cmd
+    run(cmd)
+end
+
+function generate(dir; execute=true, pluto=true)
+    quote
+        using Pkg
+        Pkg.activate(temp=true)
+        Pkg.add(name="Literate", rev="fe/pluto")
+        using Literate
+
+        const OUTDIR = $dir
+        const INFILE = joinpath(OUTDIR, "notebook.jl")
+
+        # generate pluto notebook:
+        if $pluto
+            TEMPDIR = tempdir()
+            Literate.notebook(INFILE, TEMPDIR, flavor=Literate.PlutoFlavor())
+            runcommand(`mv $TEMPDIR/notebook.jl $OUTDIR/notebook.pluto.jl`)
+        end
+
+        Literate.notebook(INFILE, OUTDIR, execute=false)
+        runcommand(
+            `mv $OUTDIR/notebook.ipynb $OUTDIR/notebook.unexecuted.ipynb`)
+        $execute && Literate.notebook(INFILE, OUTDIR, execute=true)
+
+    end |> eval
+end
+
+# Pkg.add("Pluto")
+# using Pluto
+# Pluto.run(notebook=joinpath(OUTDIR, "notebook.pluto.jl"))
+
+# Pkg.add("IJulia")
+# Pkg.instantiate()
+# using IJulia
+# IJulia.notebook(dir=OUTDIR)