Revamp documentation (#276)

* Revamp documentation

* Don't remove detector

* Sparsity tutorial

* Rename advanced

* Add docstrings

* Alignment

* Link

* No need for current module

* Examples instead of REPL in DIT

* Warning on AutoSparse and other operators

* Link

Author: gdalle

DifferentiationInterface/Project.toml

@@ -1,7 +1,7 @@
 name = "DifferentiationInterface"
 uuid = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63"
 authors = ["Guillaume Dalle", "Adrian Hill"]
-version = "0.4.1"
+version = "0.4.2"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"

DifferentiationInterface/docs/make.jl

@@ -34,9 +34,9 @@ makedocs(;
     format=Documenter.HTML(; assets=["assets/favicon.ico"]),
     pages=[
         "Home" => "index.md",
-        "Start here" => ["tutorial.md", "overview.md", "backends.md"],
-        "API reference" => "api.md",
-        "Advanced" => ["design.md", "overloads.md"],
+        "Tutorials" => ["tutorial1.md", "tutorial2.md"],
+        "Reference" => ["operators.md", "backends.md", "api.md"],
+        "Advanced" => ["preparation.md", "overloads.md"],
     ],
     checkdocs=:exports,
     plugins=[links],

DifferentiationInterface/docs/src/api.md

@@ -1,15 +1,38 @@
+# API
+
 ```@meta
-CurrentModule = Main
 CollapsedDocStrings = true
 ```
 
-# API reference
-
 ```@docs
 DifferentiationInterface
 ```
 
-## Derivative
+## First order
+
+### Pushforward
+
+```@docs
+prepare_pushforward
+prepare_pushforward_same_point
+pushforward
+pushforward!
+value_and_pushforward
+value_and_pushforward!
+```
+
+### Pullback
+
+```@docs
+prepare_pullback
+prepare_pullback_same_point
+pullback
+pullback!
+value_and_pullback
+value_and_pullback!
+```
+
+### Derivative
 
 ```@docs
 prepare_derivative
@@ -19,7 +42,7 @@ value_and_derivative
 value_and_derivative!
 ```
 
-## Gradient
+### Gradient
 
 ```@docs
 prepare_gradient
@@ -29,7 +52,7 @@ value_and_gradient
 value_and_gradient!
 ```
 
-## Jacobian
+### Jacobian
 
 ```@docs
 prepare_jacobian
@@ -45,62 +68,50 @@ value_and_jacobian!
 SecondOrder
 ```
 
+### Second derivative
+
 ```@docs
 prepare_second_derivative
 second_derivative
 second_derivative!
 ```
 
+### Hessian-vector product
+
 ```@docs
 prepare_hvp
 prepare_hvp_same_point
 hvp
 hvp!
 ```
 
+### Hessian
+
 ```@docs
 prepare_hessian
 hessian
 hessian!
 ```
 
-## Primitives
-
-```@docs
-prepare_pushforward
-prepare_pushforward_same_point
-pushforward
-pushforward!
-value_and_pushforward
-value_and_pushforward!
-```
-
-```@docs
-prepare_pullback
-prepare_pullback_same_point
-pullback
-pullback!
-value_and_pullback
-value_and_pullback!
-```
+## Utilities
 
-## Backend queries
+### Backend queries
 
 ```@docs
 check_available
 check_twoarg
 check_hessian
 ```
 
-## Miscellaneous
+### Backend switch
 
 ```@docs
 DifferentiateWith
 ```
 
 ## Internals
 
-This is not part of the public API.
+The following is not part of the public API.
 
 ```@autodocs
 Modules = [DifferentiationInterface]

DifferentiationInterface/docs/src/backends.md

@@ -1,7 +1,11 @@
-```@meta
-CurrentModule = Main
-CollapsedDocStrings = true
-```
+# Backends
+
+DifferentiationInterface.jl is based on two concepts: **operators** and **backends**.
+This page is about the latter, check out [that page](@ref "Operators") to learn about the former.
+
+## List of backends
+
+We support all dense backend choices from [ADTypes.jl](https://github.com/SciML/ADTypes.jl), as well as their sparse wrapper [`AutoSparse`](@extref ADTypes.AutoSparse).
 
 ```@setup backends
 using DifferentiationInterface
@@ -32,7 +36,7 @@ const backend_examples = (
     "AutoPolyesterForwardDiff(; chunksize=1)",
     "AutoReverseDiff()",
     "AutoSymbolics()",
-    "AutoTapir()",
+    "AutoTapir(; safe_mode=false)",
     "AutoTracker()",
     "AutoZygote()",
 )
@@ -56,14 +60,6 @@ end
 backend_table = Markdown.parse(String(take!(io)))
 ```
 
-# Backends
-
-## Types
-
-We support all dense backend choices from [ADTypes.jl](https://github.com/SciML/ADTypes.jl), as well as their sparse wrapper [`AutoSparse`](@ref).
-
-For sparse backends, only the Jacobian and Hessian operators are implemented differently, the other operators behave the same as for the corresponding dense backend.
-
 ```@example backends
 backend_table #hide
 ```
@@ -88,9 +84,30 @@ You can use [`check_available`](@ref) to verify whether a given backend is loade
 
 All backends are compatible with one-argument functions `f(x) = y`.
 Only some are compatible with two-argument functions `f!(y, x) = nothing`.
-You can check this compatibility using [`check_twoarg`](@ref).
+You can use [`check_twoarg`](@ref) to verify this compatibility.
 
 ### Support for Hessian
 
 Only some backends are able to compute Hessians.
-You can use [`check_hessian`](@ref) to check this feature (beware that it will try to compute a small Hessian, so it is not instantaneous).
+You can use [`check_hessian`](@ref) to verify this feature (beware that it will try to compute a small Hessian, so it is not instantaneous like the other checks).
+
+## Backend switch
+
+The wrapper [`DifferentiateWith`](@ref) allows you to switch between backends.
+It takes a function `f` and specifies that `f` should be differentiated with the backend of your choice, instead of whatever other backend the code is trying to use.
+In other words, when someone tries to differentiate `dw = DifferentiateWith(f, backend1)` with `backend2`, then `backend1` steps in and `backend2` does nothing.
+At the moment, `DifferentiateWith` only works when `backend2` supports [ChainRules.jl](https://github.com/JuliaDiff/ChainRules.jl).
+
+## Defining your own
+
+To work with DifferentiationInterface.jl, a new AD system would need to create an object subtyping [`ADTypes.AbstractADType`](@extref ADTypes).
+In addition, some low-level operators would need to be defined at the very least:
+
+| backend subtype                           | pushforward necessary | pullback necessary |
+| :---------------------------------------- | :-------------------- | :----------------- |
+| [`ADTypes.ForwardMode`](@extref ADTypes)  | yes                   | no                 |
+| [`ADTypes.ReverseMode`](@extref ADTypes)  | no                    | yes                |
+| [`ADTypes.SymbolicMode`](@extref ADTypes) | yes                   | yes                |
+
+Every backend we support corresponds to a package extension of DifferentiationInterface.jl (located in the `ext` subfolder).
+If you need to implement your own backend, take a look in there for inspiration, or reach out to us in the GitHub issues.