docs: make Enzyme warning more visible (#808)

Author: gdalle

DifferentiationInterface/README.md

@@ -32,7 +32,7 @@ We support the following backends defined by [ADTypes.jl](https://github.com/Sci
 
 - [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl)
 - [Diffractor.jl](https://github.com/JuliaDiff/Diffractor.jl) (currently broken)
-- [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl)
+- [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl) (see below)
 - [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl)
 - [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl)
 - [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl)
@@ -45,10 +45,8 @@ We support the following backends defined by [ADTypes.jl](https://github.com/Sci
 - [Tracker.jl](https://github.com/FluxML/Tracker.jl)
 - [Zygote.jl](https://github.com/FluxML/Zygote.jl)
 
-Note that in some cases, going through DifferentiationInterface.jl might be slower than a direct call to the backend's API.
-This is mostly true for Enzyme.jl, whose handling of activities and multiple arguments unlocks additional performance.
-We are working on this challenge, and welcome any suggestions or contributions.
-Meanwhile, if differentiation fails or takes too long, consider using Enzyme.jl directly.
+> [!CAUTION]
+> Note that in some cases, going through DifferentiationInterface.jl might be slower or cause more errors than a direct call to the backend's API. This is especially true for Enzyme.jl, whose handling of activities and multiple arguments is not fully supported here. We are working on this challenge, and welcome any suggestions or contributions. Meanwhile, if differentiation fails or takes too long, consider using Enzyme.jl through its [native API](https://enzymead.github.io/Enzyme.jl/stable/) instead.
 
 ## Installation
 

DifferentiationInterface/docs/make.jl

@@ -16,7 +16,9 @@ links = InterLinks(
     "Symbolics" => "https://symbolics.juliasymbolics.org/stable/",
 )
 
-cp(joinpath(@__DIR__, "..", "README.md"), joinpath(@__DIR__, "src", "index.md"); force=true)
+readme_str = read(joinpath(@__DIR__, "..", "README.md"), String)
+readme_str = replace(readme_str, "> [!CAUTION]\n> " => "!!! warning\n    ")
+write(joinpath(@__DIR__, "src", "index.md"), readme_str)
 
 makedocs(;
     modules=[DifferentiationInterface],

DifferentiationInterface/docs/src/explanation/backends.md

@@ -120,6 +120,10 @@ We only implement `pushforward`.
 Depending on the `mode` attribute inside [`AutoEnzyme`](@extref ADTypes.AutoEnzyme), we implement either `pushforward` or `pullback` based on `Enzyme.autodiff`.
 When necessary, preparation chooses a number of chunks (for `gradient` and `jacobian` in forward mode, for `jacobian` only in reverse mode).
 
+!!! warning
+    Enzyme.jl's handling of activities and multiple arguments is not fully supported here, which can cause slowdowns or errors.
+    If differentiation fails or takes too long, consider using Enzyme.jl through its [native API](https://enzymead.github.io/Enzyme.jl/stable/) instead.
+
 ### FastDifferentiation
 
 For every operator, preparation generates an [executable function](https://brianguenter.github.io/FastDifferentiation.jl/stable/makefunction/) from the symbolic expression of the differentiated function.