Reorganise the docs (#509)

Author: mzgubic

docs/Manifest.toml

@@ -13,7 +13,7 @@ uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 deps = ["Compat", "LinearAlgebra", "SparseArrays"]
 path = ".."
 uuid = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
-version = "1.11.0"
+version = "1.11.1"
 
 [[Compat]]
 deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "SHA", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"]

docs/make.jl

@@ -46,22 +46,37 @@ makedocs(;
     authors="Jarrett Revels and other contributors",
     pages=[
         "Introduction" => "index.md",
-        "FAQ" => "FAQ.md",
-        "Rule configurations and calling back into AD" => "config.md",
-        "Opting out of rules" => "opting_out_of_rules.md",
-        "Writing Good Rules" => "writing_good_rules.md",
-        "Complex Numbers" => "complex.md",
-        "Deriving Array Rules" => "arrays.md",
-        "Debug Mode" => "debug_mode.md",
-        "Gradient Accumulation" => "gradient_accumulation.md",
-        "Usage in AD" => "use_in_ad_system.md",
-        "Converting ZygoteRules" => "converting_zygoterules.md",
-        "Tips for making packages work with AD" => "tips_for_packages.md",
-        "Videos" => "videos.md",
+        "How to use ChainRules as a rule author" => [
+            "Introduction" => "rule_author/intro.md",
+            "Differentials" => "rule_author/differentials.md",
+            #"`frule` and `rrule`" => "rule_author/rules.md", # TODO: a complete example
+            "Writing good rules" => "rule_author/writing_good_rules.md",
+            "Testing your rules" => "rule_author/testing.md",
+            "Superpowers" => [
+                "`ProjectTo`" => "rule_author/superpowers/projectto.md",
+                "`@opt_out`" => "rule_author/superpowers/opt_out.md",
+                "`RuleConfig`" => "rule_author/superpowers/ruleconfig.md",
+                "Gradient accumulation" => "rule_author/superpowers/gradient_accumulation.md",
+            ],
+            "Converting ZygoteRules.@adjoint to rrules" => "rule_author/converting_zygoterules.md",
+            "Tips for making your package work with AD" => "rule_author/tips_for_packages.md",
+            "Debug mode" => "rule_author/debug_mode.md",
+        ],
+        "How to support ChainRules rules as an AD package author" => [
+            "Usage in AD" => "ad_author/use_in_ad_system.md",
+            "Suport calling back into ADs" => "ad_author/call_back_into_ad.md",
+            "Support opting out of rules" => "ad_author/opt_out.md",
+        ],
+        "The maths" => [
+            "The propagators: pushforward and pullback" => "maths/propagators.md",
+            "Complex numbers" => "maths/complex.md",
+            "Deriving array rules" => "maths/arrays.md",
+        ],
         "Design" => [
             "Changing the Primal" => "design/changing_the_primal.md",
             "Many Differential Types" => "design/many_differentials.md",
         ],
+        "FAQ" => "FAQ.md",
         "API" => "api.md",
     ],
     strict=true,

docs/src/ad_author/call_back_into_ad.md

@@ -0,0 +1,23 @@
+# Declaring support for calling back into ADs
+
+To declare support or lack of support for forward and reverse-mode, use the two pairs of complementary types.
+For reverse mode: [`HasReverseMode`](@ref), [`NoReverseMode`](@ref).
+For forwards mode: [`HasForwardsMode`](@ref), [`NoForwardsMode`](@ref).
+AD systems that support any calling back into AD should have one from each set.
+
+If an AD `HasReverseMode`, then it must define [`rrule_via_ad`](@ref) for that RuleConfig subtype.
+Similarly, if an AD `HasForwardsMode` then it must define [`frule_via_ad`](@ref) for that RuleConfig subtype.
+
+For example:
+```julia
+struct MyReverseOnlyADRuleConfig <: RuleConfig{Union{HasReverseMode, NoForwardsMode}} end
+
+function ChainRulesCore.rrule_via_ad(::MyReverseOnlyADRuleConfig, f, args...)
+    ...
+    return y, pullback
+end
+```
+
+Note that it is not actually required that the same AD is used for forward and reverse.
+For example [Nabla.jl](https://github.com/invenia/Nabla.jl/) is a reverse mode AD.
+It might declare that it `HasForwardsMode`, and then define a wrapper around [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) in order to provide that capacity.

docs/src/ad_author/opt_out.md

@@ -0,0 +1,33 @@
+# Support opting out of rules
+
+We provide two ways to know that a rule has been opted out of.
+
+### `rrule` / `frule` returns `nothing`
+
+`@opt_out` defines a `frule` or `rrule` matching the signature that returns `nothing`.
+
+If you are in a position to generate code, in response to values returned by function calls then you can do something like:
+```@julia
+res = rrule(f, xs)
+if res === nothing
+    y, pullback = perform_ad_via_decomposition(r, xs)  # do AD without hitting the rrule
+else
+    y, pullback = res
+end
+```
+The Julia compiler will specialize based on inferring the return type of `rrule`, and so can remove that branch.
+
+### `no_rrule` / `no_frule` has a method
+
+`@opt_out` also defines a method for  [`ChainRulesCore.no_frule`](@ref) or [`ChainRulesCore.no_rrule`](@ref).
+The body of this method doesn't matter, what matters is that it is a method-table.
+A simple thing you can do with this is not support opting out.
+To do this, filter all methods from the `rrule`/`frule` method table that also occur in the `no_frule`/`no_rrule` table.
+This will thus avoid ever hitting an `rrule`/`frule` that returns `nothing` (and thus prevents your library from erroring).
+This is easily done, though it does mean ignoring the user's stated desire to opt out of the rule.
+
+More complex you can use this to generate code that triggers your AD.
+If for a given signature there is a more specific method in the `no_rrule`/`no_frule` method-table, than the one that would be hit from the `rrule`/`frule` table
+(Excluding the one that exactly matches which will return `nothing`) then you know that the rule should not be used.
+You can, likely by looking at the primal method table, workout which method you would have it if the rule had not been defined,
+and then `invoke` it.