More stuff

DifferentiationInterface/docs/make.jl

@@ -39,7 +39,6 @@ makedocs(;
  "Reference" => ["operators.md", "backends.md", "api.md"],
  "Advanced" => ["dev_guide.md", "overloads.md"],
  ],
- checkdocs=:exports,
  plugins=[links],
 )
 

DifferentiationInterfaceTest/docs/Project.toml

@@ -5,6 +5,7 @@ DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DifferentiationInterface = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63"
 DifferentiationInterfaceTest = "a82114a7-5aa3-49a8-9643-716bb13727a3"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 Enzyme = "7da242da-08ed-463a-9acd-ee780be4f1d9"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"

DifferentiationInterfaceTest/docs/make.jl

@@ -1,6 +1,7 @@
 using DifferentiationInterface
 using DifferentiationInterfaceTest
 using Documenter
+using DocumenterInterLinks
 
 using BenchmarkTools: BenchmarkTools
 using DataFrames: DataFrames

DifferentiationInterfaceTest/docs/src/tutorial.md

@@ -42,7 +42,7 @@ xv = rand(Float32, 3)
 xm = rand(Float64, 3, 2)
 scenarios = [
  GradientScenario(f; x=xv, y=f(xv), grad=∇f(xv), nb_args=1, place=:inplace),
- GradientScenario(f; x=xm, y=f(xm), grad=∇f(xv), nb_args=1, place=:inplace)
+ GradientScenario(f; x=xm, y=f(xm), grad=∇f(xm), nb_args=1, place=:inplace)
 ];
 nothing # hide
 ```

DifferentiationInterfaceTest/src/scenarios/scenario.jl

@@ -25,6 +25,12 @@ This generic type should never be used directly: use the specific constructor co
 # Fields
 
 $(TYPEDFIELDS)
+
+Note that the `res1` and `res2` fields are given more meaningful names in the keyword arguments of each specialized constructor.
+For example:
+
+- the keyword `grad` of `GradientScenario` becomes `res1`
+- the keyword `hess` of `HessianScenario` becomes `res2`, and the keyword `grad` becomes `res1`
 """
 struct Scenario{op,args,pl,F,X,Y,D,R1,R2}
  "function `f` (if `args==1`) or `f!` (if `args==2`) to apply"
@@ -35,9 +41,9 @@ struct Scenario{op,args,pl,F,X,Y,D,R1,R2}
  y::Y
  "seed for pushforward, pullback or HVP"
  seed::D
- "first-order result"
+ "first-order result of the operator"
  res1::R1
- "second-order result"
+ "second-order result of the operator (when it makes sense)"
  res2::R2
 
  function Scenario{op,args,pl}(
@@ -120,20 +126,26 @@ end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `pushforward` and its variants.
 """
 function PushforwardScenario(f; x, y, dx, dy=nothing, nb_args, place=:inplace)
  return Scenario{:pushforward,nb_args,place}(f; x, y, seed=dx, res1=dy, res2=nothing)
 end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `pullback` and its variants.
 """
 function PullbackScenario(f; x, y, dy, dx=nothing, nb_args, place=:inplace)
  return Scenario{:pullback,nb_args,place}(f; x, y, seed=dy, res1=dx, res2=nothing)
 end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `derivative` and its variants.
 """
 function DerivativeScenario(f; x, y, der=nothing, nb_args, place=:inplace)
  return Scenario{:derivative,nb_args,place}(
@@ -143,20 +155,26 @@ end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `gradient` and its variants.
 """
 function GradientScenario(f; x, y, grad=nothing, nb_args, place=:inplace)
  return Scenario{:gradient,nb_args,place}(f; x, y, seed=nothing, res1=grad, res2=nothing)
 end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `jacobian` and its variants.
 """
 function JacobianScenario(f; x, y, jac=nothing, nb_args, place=:inplace)
  return Scenario{:jacobian,nb_args,place}(f; x, y, seed=nothing, res1=jac, res2=nothing)
 end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `second_derivative` and its variants.
 """
 function SecondDerivativeScenario(
  f; x, y, der=nothing, der2=nothing, nb_args, place=:inplace
@@ -168,13 +186,17 @@ end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `hvp` and its variants.
 """
 function HVPScenario(f; x, y, dx, grad=nothing, dg=nothing, nb_args, place=:inplace)
  return Scenario{:hvp,nb_args,place}(f; x, y, seed=dx, res1=grad, res2=dg)
 end
 
 """
 $(SIGNATURES)
+
+Construct a [`Scenario`](@ref) to test `hessian` and its variants.
 """
 function HessianScenario(f; x, y, grad=nothing, hess=nothing, nb_args, place=:inplace)
  return Scenario{:hessian,nb_args,place}(f; x, y, seed=nothing, res1=grad, res2=hess)