make guide + reference

Author: mcabbott

docs/make.jl

@@ -9,44 +9,45 @@ makedocs(
     sitename = "Flux",
     # strict = [:cross_references,],
     pages = [
-        "Getting Started" => [
-            "Welcome" => "index.md",
+        "Welcome" => "index.md",
+        "Guide" => [
+        # You could read this end-to-end, or skip to what you need.
+        # Aim is to cover each new concept exactly once (but not list all variants).
+        # Hard to invent further divisions which aren't more confusing than helpful?
             "Quick Start" => "models/quickstart.md",
             "Fitting a Line" => "models/overview.md",
             "Gradients and Layers" => "models/basics.md",
+            "Training" => "training/training.md",
+            "Regularisation" => "models/regularisation.md",
+            "Recurrence" => "models/recurrence.md",
+            "GPU Support" => "gpu.md",
+            "Saving & Loading" => "saving.md",
+            "Performance Tips" => "performance.md",
         ],
-        "Building Models" => [
+        "Reference" => [
+        # This essentially collects docstrings, with a bit of introduction.
+        # Probably the 📚 marker can be removed now.
             "Built-in Layers 📚" => "models/layers.md",
-            "Recurrence" => "models/recurrence.md",
             "Activation Functions 📚" => "models/activation.md",
+            "Weight Initialisation 📚" => "utilities.md",
+            "Loss Functions 📚" => "models/losses.md",
+            "Optimisation Rules 📚" => "training/optimisers.md",  # TODO move optimiser intro up to Training
+            "Shape Inference 📚" => "outputsize.md",
+            "Flat vs. Nested 📚" => "destructure.md",
+            "Callback Helpers 📚" => "training/callbacks.md",
             "NNlib.jl 📚 (`softmax`, `conv`, ...)" => "models/nnlib.md",
+            "Zygote.jl 📚 (`gradient`, ...)" => "training/zygote.md",
+            "MLUtils.jl 📚 (`DataLoader`, ...)" => "data/mlutils.md",
+            "Functors.jl 📚 (`fmap`, ...)" => "models/functors.md",
+            "OneHotArrays.jl 📚 (`onehot`, ...)" => "data/onehot.md",
          ],
-         "Handling Data" => [
-             "MLUtils.jl 📚 (`DataLoader`, ...)" => "data/mlutils.md",
-             "OneHotArrays.jl 📚 (`onehot`, ...)" => "data/onehot.md",
-         ],
-         "Training Models" => [
-             "Training" => "training/training.md",
-             "Regularisation" => "models/regularisation.md",
-             "Loss Functions 📚" => "models/losses.md",
-             "Optimisation Rules 📚" => "training/optimisers.md",  # TODO move optimiser intro up to Training
-             "Callback Helpers 📚" => "training/callbacks.md",
-             "Zygote.jl 📚 (`gradient`, ...)" => "training/zygote.md",
-         ],
-         "Model Tools" => [
-             "GPU Support" => "gpu.md",
-             "Saving & Loading" => "saving.md",
-             "Shape Inference 📚" => "outputsize.md",
-             "Weight Initialisation 📚" => "utilities.md",
-             "Flat vs. Nested 📚" => "destructure.md",
-             "Functors.jl 📚 (`fmap`, ...)" => "models/functors.md",
-         ],
-         "Tutorials" => [
+        "Flux's Ecosystem" => "ecosystem.md",  # This is a links page
+        "Tutorials" => [
+        # These walk you through various tasks. It's fine if they overlap quite a lot.
+        # All the website tutorials can move here, perhaps much of the model zoo too.
             "Linear Regression" => "tutorials/linear_regression.md",
             "Custom Layers" => "models/advanced.md",  # TODO move freezing to Training
-         ],
-         "Performance Tips" => "performance.md",
-         "Flux's Ecosystem" => "ecosystem.md",
+        ],
     ],
     format = Documenter.HTML(
         sidebar_sitename = false,