Add FAQ section to docs (#1343)

* Explain why Duplicated requires identical types * Restructure docs * Remove noise * Doctest setup * Wrong page name * Fix ref * Fix error message * Fix links * Add remarks * More remarks * Rename section
EnzymeAD · Mar 22, 2024 · 71b685a · 71b685a
1 parent 2e1b77e
commit 71b685a
Show file tree

Hide file tree

Showing 8 changed files with 431 additions and 401 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -21,8 +21,8 @@ const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
 const OUTPUT_DIR = joinpath(@__DIR__, "src/generated")
 
 examples = Pair{String,String}[
+    "Basics" => "autodiff"
     "Box model" => "box"
-    "AutoDiff API" => "autodiff"
     "Custom rules" => "custom_rule"
 ]
 
@@ -51,10 +51,12 @@ makedocs(;
     pages = [
         "Home" => "index.md",
         "Examples" => examples,
-        "API" => "api.md",
-        "Implementing pullbacks" => "pullbacks.md",
-        "For developers" => "dev_docs.md",
-        "Internal API" => "internal_api.md",
+        "FAQ" => "faq.md",
+        "API reference" => "api.md",
+        "Advanced" => [
+            "For developers" => "dev_docs.md",
+            "Internal API" => "internal_api.md",
+        ]
     ],
     doctest = true,
     strict = true,

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -1,4 +1,4 @@
-# API
+# API reference
 
 ## Types and constants
 
@@ -14,7 +14,7 @@ Modules = [Enzyme, EnzymeCore, EnzymeCore.EnzymeRules, EnzymeTestUtils, Enzyme.A
 Order = [:macro, :function]
 ```
 
-# Documentation
+## Documentation
 
 ```@autodocs
 Modules = [Enzyme, EnzymeCore, EnzymeCore.EnzymeRules, EnzymeTestUtils, Enzyme.API]

diff --git a/docs/src/faq.md b/docs/src/faq.md
diff --git a/docs/src/index.md b/docs/src/index.md
diff --git a/docs/src/pullbacks.md b/docs/src/pullbacks.md
diff --git a/examples/autodiff.jl b/examples/autodiff.jl
@@ -1,4 +1,4 @@
-# # AutoDiff API
+# # Basics
 
 # The goal of this tutorial is to give users already familiar with automatic
 # differentiation (AD) an overview

diff --git a/src/Enzyme.jl b/src/Enzyme.jl
@@ -264,7 +264,7 @@ Enzyme.autodiff(ReverseWithPrimal, x->x*x, Active(3.0))
             return (fused, results[2:end]...)
         end
 
-        throw(ErrorException("Reverse-mode Active Complex return is ambiguous and requires more information to specify the desired result. See https://enzyme.mit.edu/julia/stable/#Complex for more details."))
+        throw(ErrorException("Reverse-mode Active Complex return is ambiguous and requires more information to specify the desired result. See https://enzyme.mit.edu/julia/stable/faq/#Complex-numbers for more details."))
     end
 
     thunk = Enzyme.Compiler.thunk(Val(world), FA, A, tt′, #=Split=# Val(API.DEM_ReverseModeCombined), Val(width), ModifiedBetween, Val(ReturnPrimal), #=ShadowInit=#Val(false), RABI)

diff --git a/src/compiler.jl b/src/compiler.jl
@@ -513,7 +513,7 @@ end
             return true
         end
         @assert state == MixedState
-        throw(AssertionError(string(T)*" has mixed internal activity types. See https://enzyme.mit.edu/julia/dev/#Mixed-Activity for more information"))
+        throw(AssertionError(string(T)*" has mixed internal activity types. See https://enzyme.mit.edu/julia/stable/faq/#Mixed-activity for more information"))
     else
         return false
     end
@@ -1820,7 +1820,7 @@ function julia_error(cstr::Cstring, val::LLVM.API.LLVMValueRef, errtype::API.Err
                 println(io, Base.unsafe_string(st))
                 API.EnzymeStringFree(st)
             end
-            println(io, "You may be using a constant variable as temporary storage for active memory (https://enzyme.mit.edu/julia/stable/#Activity-of-temporary-storage). If not, please open an issue, and either rewrite this variable to not be conditionally active or use Enzyme.API.runtimeActivity!(true) as a workaround for now")
+            println(io, "You may be using a constant variable as temporary storage for active memory (https://enzyme.mit.edu/julia/stable/faq/#Activity-of-temporary-storage). If not, please open an issue, and either rewrite this variable to not be conditionally active or use Enzyme.API.runtimeActivity!(true) as a workaround for now")
             if bt !== nothing
                 Base.show_backtrace(io, bt)
             end