have markdown for workflows use @example fencing

oops

docs/make.jl

@@ -25,30 +25,35 @@ makedocs(
     warnonly = true,
     pages = [
         "Introduction" => "index.md",
-        "Interface"=> Any[
-            "Summary"=>"interface/Summary.md",
-            "Builders"=>"interface/Builders.md",
-            "Custom Builders"=>"interface/Custom Builders.md",
-            "Classification"=>"interface/Classification.md",
-            "Regression"=>"interface/Regression.md",
-            "Multi-Target Regression"=>"interface/Multitarget Regression.md",
-            "Image Classification"=>"interface/Image Classification.md",
+        "Interface" => Any[
+            "Summary" => "interface/Summary.md",
+            "Builders" => "interface/Builders.md",
+            "Custom Builders" => "interface/Custom Builders.md",
+            "Classification" => "interface/Classification.md",
+            "Regression" => "interface/Regression.md",
+            "Multi-Target Regression" => "interface/Multitarget Regression.md",
+            "Image Classification" => "interface/Image Classification.md",
         ],
-        "Workflow Examples" => Any[
-            "Incremental Training"=>
+        "Common Workflows" => Any[
+            "Incremental Training" =>
                 "common_workflows/incremental_training/notebook.md",
-            "Hyperparameter Tuning"=>
+            "Hyperparameter Tuning" =>
                 "common_workflows/hyperparameter_tuning/notebook.md",
-            "Neural Architecture Search"=>
+            "Model Composition" =>
+                "common_workflows/composition/notebook.md",
+            "Model Comparison" =>
+                "common_workflows/comparison/notebook.md",
+            "Early Stopping" =>
+                "common_workflows/early_stopping/notebook.md",
+            "Live Training" =>
+                "common_workflows/live_training/notebook.md",
+            "Neural Architecture Search" =>
                 "common_workflows/architecture_search/notebook.md",
-            "Model Composition"=>"common_workflows/composition/notebook.md",
-            "Model Comparison"=>"common_workflows/comparison/notebook.md",
-            "Early Stopping"=>"common_workflows/early_stopping/notebook.md",
-            "Live Training"=>"common_workflows/live_training/notebook.md",
         ],
-        # "Tutorials"=>Any[
-        # "Spam Detection with RNNs"=>"extended_examples/Spam Detection with RNNs/notebook.md"
-        # ],
+        "Extended Examples" => Any[
+            "MNIST Images" => "extended_examples/MNIST/notebook.md",
+            "Spam Detection with RNNs" => "extended_examples/spam_detection/notebook.md",
+        ],
         "Contributing" => "contributing.md"],
     doctest = false,
 )

docs/src/common_workflows/architecture_search/notebook.ipynb

@@ -10,9 +10,18 @@
   {
    "cell_type": "markdown",
    "source": [
-    "Neural Architecture Search is (NAS) is an instance of hyperparameter tuning concerned with tuning model hyperparameters\n",
-    "defining the architecture itself. Although it's typically performed with sophisticated search algorithms for efficiency,\n",
-    "in this example we will be using a simple random search."
+    "This demonstration is available as a Jupyter notebook or julia script\n",
+    "[here](https://github.com/FluxML/MLJFlux.jl/tree/dev/docs/src/common_workflows/architecture_search)."
+   ],
+   "metadata": {}
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Neural Architecture Search (NAS) is an instance of hyperparameter tuning concerned\n",
+    "with tuning model hyperparameters defining the architecture itself. Although it's\n",
+    "typically performed with sophisticated search algorithms for efficiency, in this example\n",
+    "we will be using a simple random search."
    ],
    "metadata": {}
   },
@@ -22,7 +31,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "  Activating project at `~/GoogleDrive/Julia/MLJ/MLJFlux/docs/src/workflow examples/Basic Neural Architecture Search`\n"
+      "  Activating project at `~/GoogleDrive/Julia/MLJ/MLJFlux/docs/src/common_workflows/architecture_search`\n"
      ]
     }
    ],
@@ -121,7 +130,7 @@
     {
      "output_type": "execute_result",
      "data": {
-      "text/plain": "NeuralNetworkClassifier(\n  builder = MLP(\n        hidden = (1, 1, 1), \n        σ = NNlib.relu), \n  finaliser = NNlib.softmax, \n  optimiser = Adam(0.01, (0.9, 0.999), 1.0e-8), \n  loss = Flux.Losses.crossentropy, \n  epochs = 10, \n  batch_size = 8, \n  lambda = 0.0, \n  alpha = 0.0, \n  rng = 42, \n  optimiser_changes_trigger_retraining = false, \n  acceleration = CPU1{Nothing}(nothing))"
+      "text/plain": "NeuralNetworkClassifier(\n  builder = MLP(\n        hidden = (1, 1, 1), \n        σ = NNlib.relu), \n  finaliser = NNlib.softmax, \n  optimiser = Adam(0.01, (0.9, 0.999), 1.0e-8), \n  loss = Flux.Losses.crossentropy, \n  epochs = 10, \n  batch_size = 8, \n  lambda = 0.0, \n  alpha = 0.0, \n  rng = 42, \n  optimiser_changes_trigger_retraining = false, \n  acceleration = ComputationalResources.CPU1{Nothing}(nothing))"
      },
      "metadata": {},
      "execution_count": 4
@@ -297,7 +306,7 @@
     {
      "output_type": "execute_result",
      "data": {
-      "text/plain": "NeuralNetworkClassifier(\n  builder = MLP(\n        hidden = (9, 37, 25), \n        σ = NNlib.relu), \n  finaliser = NNlib.softmax, \n  optimiser = Adam(0.01, (0.9, 0.999), 1.0e-8), \n  loss = Flux.Losses.crossentropy, \n  epochs = 10, \n  batch_size = 8, \n  lambda = 0.0, \n  alpha = 0.0, \n  rng = 42, \n  optimiser_changes_trigger_retraining = false, \n  acceleration = CPU1{Nothing}(nothing))"
+      "text/plain": "NeuralNetworkClassifier(\n  builder = MLP(\n        hidden = (21, 57, 25), \n        σ = NNlib.relu), \n  finaliser = NNlib.softmax, \n  optimiser = Adam(0.01, (0.9, 0.999), 1.0e-8), \n  loss = Flux.Losses.crossentropy, \n  epochs = 10, \n  batch_size = 8, \n  lambda = 0.0, \n  alpha = 0.0, \n  rng = 42, \n  optimiser_changes_trigger_retraining = false, \n  acceleration = ComputationalResources.CPU1{Nothing}(nothing))"
      },
      "metadata": {},
      "execution_count": 8
@@ -332,9 +341,9 @@
     {
      "output_type": "execute_result",
      "data": {
-      "text/plain": "\u001b[1m10×2 DataFrame\u001b[0m\n\u001b[1m Row \u001b[0m│\u001b[1m mlp                           \u001b[0m\u001b[1m measurement \u001b[0m\n     │\u001b[90m MLP…                          \u001b[0m\u001b[90m Float64     \u001b[0m\n─────┼────────────────────────────────────────────\n   1 │ MLP(hidden = (9, 37, 25), …)     0.0623247\n   2 │ MLP(hidden = (21, 29, 49), …)    0.0779369\n   3 │ MLP(hidden = (25, 9, 45), …)     0.0803409\n   4 │ MLP(hidden = (33, 25, 57), …)    0.0857974\n   5 │ MLP(hidden = (25, 45, 33), …)    0.0877367\n   6 │ MLP(hidden = (33, 17, 49), …)    0.0887764\n   7 │ MLP(hidden = (33, 9, 49), …)     0.0892747\n   8 │ MLP(hidden = (29, 29, 41), …)    0.0951306\n   9 │ MLP(hidden = (41, 37, 57), …)    0.0953401\n  10 │ MLP(hidden = (25, 49, 25), …)    0.0960489",
+      "text/plain": "\u001b[1m10×2 DataFrame\u001b[0m\n\u001b[1m Row \u001b[0m│\u001b[1m mlp                           \u001b[0m\u001b[1m measurement \u001b[0m\n     │\u001b[90m MLP…                          \u001b[0m\u001b[90m Float64     \u001b[0m\n─────┼────────────────────────────────────────────\n   1 │ MLP(hidden = (21, 57, 25), …)    0.0867019\n   2 │ MLP(hidden = (45, 17, 13), …)    0.0929803\n   3 │ MLP(hidden = (33, 13, 49), …)    0.0973896\n   4 │ MLP(hidden = (21, 41, 61), …)    0.0981502\n   5 │ MLP(hidden = (57, 49, 61), …)    0.100331\n   6 │ MLP(hidden = (25, 25, 29), …)    0.101083\n   7 │ MLP(hidden = (29, 61, 21), …)    0.101466\n   8 │ MLP(hidden = (29, 61, 5), …)     0.107513\n   9 │ MLP(hidden = (21, 61, 17), …)    0.107874\n  10 │ MLP(hidden = (45, 49, 61), …)    0.111292",
       "text/html": [
-       "<div><div style = \"float: left;\"><span>10×2 DataFrame</span></div><div style = \"clear: both;\"></div></div><div class = \"data-frame\" style = \"overflow-x: scroll;\"><table class = \"data-frame\" style = \"margin-bottom: 6px;\"><thead><tr class = \"header\"><th class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">Row</th><th style = \"text-align: left;\">mlp</th><th style = \"text-align: left;\">measurement</th></tr><tr class = \"subheader headerLastRow\"><th class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\"></th><th title = \"MLJFlux.MLP{3}\" style = \"text-align: left;\">MLP…</th><th title = \"Float64\" style = \"text-align: left;\">Float64</th></tr></thead><tbody><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">1</td><td style = \"text-align: left;\">MLP(hidden = (9, 37, 25), …)</td><td style = \"text-align: right;\">0.0623247</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">2</td><td style = \"text-align: left;\">MLP(hidden = (21, 29, 49), …)</td><td style = \"text-align: right;\">0.0779369</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">3</td><td style = \"text-align: left;\">MLP(hidden = (25, 9, 45), …)</td><td style = \"text-align: right;\">0.0803409</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">4</td><td style = \"text-align: left;\">MLP(hidden = (33, 25, 57), …)</td><td style = \"text-align: right;\">0.0857974</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">5</td><td style = \"text-align: left;\">MLP(hidden = (25, 45, 33), …)</td><td style = \"text-align: right;\">0.0877367</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">6</td><td style = \"text-align: left;\">MLP(hidden = (33, 17, 49), …)</td><td style = \"text-align: right;\">0.0887764</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">7</td><td style = \"text-align: left;\">MLP(hidden = (33, 9, 49), …)</td><td style = \"text-align: right;\">0.0892747</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">8</td><td style = \"text-align: left;\">MLP(hidden = (29, 29, 41), …)</td><td style = \"text-align: right;\">0.0951306</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">9</td><td style = \"text-align: left;\">MLP(hidden = (41, 37, 57), …)</td><td style = \"text-align: right;\">0.0953401</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">10</td><td style = \"text-align: left;\">MLP(hidden = (25, 49, 25), …)</td><td style = \"text-align: right;\">0.0960489</td></tr></tbody></table></div>"
+       "<div><div style = \"float: left;\"><span>10×2 DataFrame</span></div><div style = \"clear: both;\"></div></div><div class = \"data-frame\" style = \"overflow-x: scroll;\"><table class = \"data-frame\" style = \"margin-bottom: 6px;\"><thead><tr class = \"header\"><th class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">Row</th><th style = \"text-align: left;\">mlp</th><th style = \"text-align: left;\">measurement</th></tr><tr class = \"subheader headerLastRow\"><th class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\"></th><th title = \"MLJFlux.MLP{3}\" style = \"text-align: left;\">MLP…</th><th title = \"Float64\" style = \"text-align: left;\">Float64</th></tr></thead><tbody><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">1</td><td style = \"text-align: left;\">MLP(hidden = (21, 57, 25), …)</td><td style = \"text-align: right;\">0.0867019</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">2</td><td style = \"text-align: left;\">MLP(hidden = (45, 17, 13), …)</td><td style = \"text-align: right;\">0.0929803</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">3</td><td style = \"text-align: left;\">MLP(hidden = (33, 13, 49), …)</td><td style = \"text-align: right;\">0.0973896</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">4</td><td style = \"text-align: left;\">MLP(hidden = (21, 41, 61), …)</td><td style = \"text-align: right;\">0.0981502</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">5</td><td style = \"text-align: left;\">MLP(hidden = (57, 49, 61), …)</td><td style = \"text-align: right;\">0.100331</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">6</td><td style = \"text-align: left;\">MLP(hidden = (25, 25, 29), …)</td><td style = \"text-align: right;\">0.101083</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">7</td><td style = \"text-align: left;\">MLP(hidden = (29, 61, 21), …)</td><td style = \"text-align: right;\">0.101466</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">8</td><td style = \"text-align: left;\">MLP(hidden = (29, 61, 5), …)</td><td style = \"text-align: right;\">0.107513</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">9</td><td style = \"text-align: left;\">MLP(hidden = (21, 61, 17), …)</td><td style = \"text-align: right;\">0.107874</td></tr><tr><td class = \"rowNumber\" style = \"font-weight: bold; text-align: right;\">10</td><td style = \"text-align: left;\">MLP(hidden = (45, 49, 61), …)</td><td style = \"text-align: right;\">0.111292</td></tr></tbody></table></div>"
       ]
      },
      "metadata": {},

docs/src/common_workflows/architecture_search/notebook.jl

@@ -1,6 +1,9 @@
 # # Neural Architecture Search with MLJFlux
 
-# Neural Architecture Search is (NAS) is an instance of hyperparameter tuning concerned
+# This demonstration is available as a Jupyter notebook or julia script
+# [here](https://github.com/FluxML/MLJFlux.jl/tree/dev/docs/src/common_workflows/architecture_search).
+
+# Neural Architecture Search (NAS) is an instance of hyperparameter tuning concerned
 # with tuning model hyperparameters defining the architecture itself. Although it's
 # typically performed with sophisticated search algorithms for efficiency, in this example
 # we will be using a simple random search.
@@ -9,9 +12,7 @@ using Pkg     #!md
 Pkg.activate(@__DIR__);     #!md
 Pkg.instantiate();     #!md
 
-# **Julia version** is assumed to be 1.10.* This tutorial is available as a Jupyter
-# notebook or julia script
-# [here](https://github.com/FluxML/MLJFlux.jl/tree/dev/docs/src/common_workflows/architecture_search).
+# **Julia version** is assumed to be 1.10.*
 
 # ### Basic Imports
 

docs/src/common_workflows/architecture_search/notebook.md

@@ -4,15 +4,19 @@ EditURL = "notebook.jl"
 
 # Neural Architecture Search with MLJFlux
 
-Neural Architecture Search is (NAS) is an instance of hyperparameter tuning concerned with tuning model hyperparameters
-defining the architecture itself. Although it's typically performed with sophisticated search algorithms for efficiency,
-in this example we will be using a simple random search.
+This demonstration is available as a Jupyter notebook or julia script
+[here](https://github.com/FluxML/MLJFlux.jl/tree/dev/docs/src/common_workflows/architecture_search).
+
+Neural Architecture Search (NAS) is an instance of hyperparameter tuning concerned
+with tuning model hyperparameters defining the architecture itself. Although it's
+typically performed with sophisticated search algorithms for efficiency, in this example
+we will be using a simple random search.
 
 **Julia version** is assumed to be 1.10.*
 
 ### Basic Imports
 
-````@julia
+````@example architecture_search
 using MLJ               # Has MLJFlux models
 using Flux              # For more flexibility
 using RDatasets: RDatasets        # Dataset source
@@ -22,7 +26,7 @@ import Optimisers       # native Flux.jl optimisers no longer supported
 
 ### Loading and Splitting the Data
 
-````@julia
+````@example architecture_search
 iris = RDatasets.dataset("datasets", "iris");
 y, X = unpack(iris, ==(:Species), colname -> true, rng = 123);
 X = Float32.(X);      # To be compatible with type of network network parameters
@@ -34,7 +38,7 @@ first(X, 5)
 Now let's construct our model. This follows a similar setup the one followed in the
 [Quick Start](../../index.md#Quick-Start).
 
-````@julia
+````@example architecture_search
 NeuralNetworkClassifier = @load NeuralNetworkClassifier pkg = "MLJFlux"
 clf = NeuralNetworkClassifier(
     builder = MLJFlux.MLP(; hidden = (1, 1, 1), σ = Flux.relu),
@@ -53,7 +57,7 @@ proceed by defining a function that can generate all possible networks with a sp
 number of hidden layers, a minimum and maximum number of neurons per layer and
 increments to consider for the number of neurons.
 
-````@julia
+````@example architecture_search
 function generate_networks(
     ;min_neurons::Int,
     max_neurons::Int,
@@ -93,7 +97,7 @@ end
 Now let's generate an array of all possible neural networks with three hidden layers and
 number of neurons per layer ∈ [1,64] with a step of 4
 
-````@julia
+````@example architecture_search
 networks_space =
     generate_networks(
         min_neurons = 1,
@@ -110,7 +114,7 @@ networks_space[1:5]
 Let's use this array to define the range of hyperparameters and pass it along with the
 model to the `TunedModel` constructor.
 
-````@julia
+````@example architecture_search
 r1 = range(clf, :(builder.hidden), values = networks_space)
 
 tuned_clf = TunedModel(
@@ -129,7 +133,7 @@ nothing #hide
 Similar to the last workflow example, all we need now is to fit our model and the search
 will take place automatically:
 
-````@julia
+````@example architecture_search
 mach = machine(tuned_clf, X, y);
 fit!(mach, verbosity = 0);
 fitted_params(mach).best_model
@@ -140,7 +144,7 @@ fitted_params(mach).best_model
 Let's analyze the search results by converting the history array to a dataframe and
 viewing it:
 
-````@julia
+````@example architecture_search
 history = report(mach).history
 history_df = DataFrame(
     mlp = [x[:model].builder for x in history],

docs/src/common_workflows/architecture_search/notebook.unexecuted.ipynb

@@ -10,9 +10,18 @@
   {
    "cell_type": "markdown",
    "source": [
-    "Neural Architecture Search is (NAS) is an instance of hyperparameter tuning concerned with tuning model hyperparameters\n",
-    "defining the architecture itself. Although it's typically performed with sophisticated search algorithms for efficiency,\n",
-    "in this example we will be using a simple random search."
+    "This demonstration is available as a Jupyter notebook or julia script\n",
+    "[here](https://github.com/FluxML/MLJFlux.jl/tree/dev/docs/src/common_workflows/architecture_search)."
+   ],
+   "metadata": {}
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Neural Architecture Search (NAS) is an instance of hyperparameter tuning concerned\n",
+    "with tuning model hyperparameters defining the architecture itself. Although it's\n",
+    "typically performed with sophisticated search algorithms for efficiency, in this example\n",
+    "we will be using a simple random search."
    ],
    "metadata": {}
   },