break up docs

Author: oxinabox

docs/make.jl

@@ -16,6 +16,10 @@ makedocs(
     authors="Lyndon White and other contributors",
     pages=[
         "Introduction" => "index.md",
+        "Examples of making AD systems" => [
+            "Forward Mode" => "examples/forward_mode.md",
+            "Reverse Mode" => "examples/reverse_mode.md",
+        ],
         "API" => "api.md",
        ],
     strict=true,

docs/src/examples/forward_mode.md

@@ -0,0 +1,15 @@
+# ForwardDiffZero
+This is a fairly standard operator overloading-based forward mode AD system.
+It defines a `Dual` part which holds both the primal value, paired with the partial deriviative.
+It doesn't handle chunked-mode, or perturbation confusion.
+The overload generation hook in this example is: `define_dual_overload`.
+
+````@eval
+using Markdown
+Markdown.parse("""
+```julia
+$(read(joinpath(@__DIR__,"../../../test/demos/forwarddiffzero.jl"), String))
+```
+""")
+````
+

docs/src/examples/reverse_mode.md

@@ -0,0 +1,16 @@
+
+# ReverseDiffZero
+This is a fairly standard operator overloading based reverse mode AD system.
+It defines a `Tracked` type which carries the primal value as well as a reference to the tape which is it using, a partially accumulated partial derivative and a `propagate` function that propagates it's partial back to its input.
+A perhaps unusual thing about it is how little it carries around it's creating operator's inputs.
+That information is all entirely wrapped up in the `propagate` function.
+The overload generation hook in this example is: `define_tracked_overload`.
+
+````@eval
+using Markdown
+Markdown.parse("""
+```julia
+$(read(joinpath(@__DIR__,"../../../test/demos/reversediffzero.jl"), String))
+```
+""")
+````

docs/src/index.md

@@ -57,29 +57,4 @@ When the rules are refreshed (automatically or manually), the hooks are only tri
 `clear_new_rule_hooks!`(@ref) clears all registered hooks.
 It is useful to undo [`on_new_rule`] hook registration if you are iteratively developing your overload generation function.
 
-## Examples
-Here we define two fairly simplistic operator overloading based AD Systems to demonstrate how this is used.
 
-### ForwardDiffZero
-The overload generation hook in this example is: `define_dual_overload`.
-
-````@eval
-using Markdown
-Markdown.parse("""
-```julia
-$(read(joinpath(@__DIR__,"../../test/demos/forwarddiffzero.jl"), String))
-```
-""")
-````
-
-### ReverseDiffZero
-The overload generation hook in this example is: `define_tracked_overload`.
-
-````@eval
-using Markdown
-Markdown.parse("""
-```julia
-$(read(joinpath(@__DIR__,"../../test/demos/reversediffzero.jl"), String))
-```
-""")
-````

test/demos/reversediffzero.jl

@@ -19,7 +19,7 @@ struct Tracked{F} <: Real
     propagate::F
     primal::Float64
     tape::Vector{Tracked}  # a reference to a shared tape
-    partial::Base.RefValue{Float64} # current accumulated sensitivity
+    partial::Base.RefValue{Float64}  # current accumulated sensitivity
 end
 
 "An intermediate value, a Branch in Nabla terms."
@@ -29,15 +29,15 @@ function Tracked(propagate, primal, tape)
     return v
 end
 
-"Marker for inputs (leaves) that don't need to propagate."
-struct NoPropagate end
-
 "An input, a Leaf in Nabla terms. No inputs of its own to propagate to."
 function Tracked(primal, tape)
     # don't actually need to put these on the tape, since they don't need to propagate
     return Tracked(NoPropagate(), primal, tape, Ref(zero(primal)))
 end
 
+"Marker for inputs (leaves) that don't need to propagate."
+struct NoPropagate end
+
 primal(d::Tracked) = d.primal
 primal(d) = d