Fix doctests (#2265)

* Fix doctests

The filter already attempted to address the issue, but the syntax was incorrect
with the result that no substitution was applied.

Also, remove messing with `LOAD_PATH` and use `sources` section in docs project.

* Add some color to life

Author: giordano

.github/workflows/CI.yml

@@ -95,16 +95,16 @@ jobs:
         continue-on-error: ${{ matrix.version == 'nightly' }}
         id: build_libenzyme
         run: |
-          julia --project=deps -e 'using Pkg; Pkg.instantiate()'
-          julia --project=deps deps/build_local.jl
+          julia --color=yes --project=deps -e 'using Pkg; Pkg.instantiate()'
+          julia --color=yes --project=deps deps/build_local.jl
           cp LocalPreferences.toml test/
       - name: Build libEnzyme MacOS
         if: ${{ matrix.libEnzyme == 'local' && matrix.os == 'macOS-latest'}}
         continue-on-error: ${{ matrix.version == 'nightly' }}
         id: build_libenzyme_mac
         run: |
-          julia --project=deps -e 'using Pkg; Pkg.instantiate()'
-          SDKROOT=`xcrun --show-sdk-path` julia --project=deps deps/build_local.jl
+          julia --color=yes --project=deps -e 'using Pkg; Pkg.instantiate()'
+          SDKROOT=`xcrun --show-sdk-path` julia --color=yes --project=deps deps/build_local.jl
           cp LocalPreferences.toml test/
       - uses: julia-actions/julia-buildpkg@v1
         if: matrix.version != 'nightly' || steps.build_libenzyme.outcome == 'success' || steps.build_libenzyme_mac.outcome == 'success'
@@ -287,19 +287,18 @@ jobs:
           version: '1'
       - uses: julia-actions/cache@v2
       - run: |
-          julia --project=docs -e '
+          julia --color=yes --project=docs -e '
             using Pkg
-            Pkg.develop([PackageSpec(path="lib/EnzymeCore"), PackageSpec(path="lib/EnzymeTestUtils"), PackageSpec(path=pwd())])
             Pkg.instantiate()'
         env:
           JULIA_PKG_SERVER_REGISTRY_PREFERENCE: eager
       - run: |
-          julia --project=docs -e '
+          julia --color=yes --project=docs -e '
             using Documenter: DocMeta, doctest
             using Enzyme
             DocMeta.setdocmeta!(Enzyme, :DocTestSetup, :(using Enzyme); recursive=true)
             doctest(Enzyme)'
-      - run: julia --project=docs docs/make.jl
+      - run: julia --color=yes --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -7,5 +7,6 @@ lib/EnzymeCore/Manifest.toml
 /test/Manifest.toml
 /docs/Manifest.toml
 /docs/build/
+/docs/src/generated/
 
 .vscode

docs/Project.toml

@@ -1,9 +1,16 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Enzyme = "7da242da-08ed-463a-9acd-ee780be4f1d9"
+EnzymeCore = "f151be2c-9106-41f4-ab19-57ee4f262869"
+EnzymeTestUtils = "12d8515a-0907-448a-8884-5fe00fdf1c5a"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
 Documenter = "1"
 Literate = "2"
+
+[sources]
+Enzyme = {path = ".."}
+EnzymeCore = {path = "../lib/EnzymeCore"}
+EnzymeTestUtils = {path = "../lib/EnzymeTestUtils"}

docs/make.jl

@@ -1,6 +1,3 @@
-pushfirst!(LOAD_PATH, joinpath(@__DIR__, "..")) # add Enzyme to environment stack
-pushfirst!(LOAD_PATH, joinpath(@__DIR__, "..", "lib")) # add EnzymeCore to environment stack
-
 using Enzyme
 using EnzymeCore
 using EnzymeTestUtils

docs/src/index.md

@@ -227,7 +227,7 @@ Enzyme provides convenience functions for second-order derivative computations,
 
 Unlike [`autodiff`](@ref) and [`gradient`](@ref), a mode is not specified. Here, Enzyme will choose to perform forward over reverse mode (generally the fastest for this type of operation).
 
-```jldoctest hvp; filter = r"([0-9]+\\.[0-9]{8})[0-9]+" => s"\\1***"
+```jldoctest hvp; filter = r"([0-9]+\.[0-9]{8})[0-9]+" => s"\1***"
 julia> f(x) = sin(x[1] * x[2]);
 
 julia> hvp(f, [2.0, 3.0], [5.0, 2.7])
@@ -238,7 +238,7 @@ julia> hvp(f, [2.0, 3.0], [5.0, 2.7])
 
 Enzyme also provides an in-place variant which will store the hessian vector product in a pre-allocated array (this will, however, still allocate another array for storing an intermediate gradient).
 
-```jldoctest hvp2; filter = r"([0-9]+\\.[0-9]{8})[0-9]+" => s"\\1***"
+```jldoctest hvp2; filter = r"([0-9]+\.[0-9]{8})[0-9]+" => s"\1***"
 julia> f(x) = sin(x[1] * x[2])
 f (generic function with 1 method)
 
@@ -254,7 +254,7 @@ julia> res
 
 Finally. Enzyme provides a second in-place variant which simultaneously computes both the hessian vector product, and the gradient. This function uses no additional allocation, and is much more efficient than separately computing the hvp and the gradient.
 
-```jldoctest hvp3; filter = r"([0-9]+\\.[0-9]{8})[0-9]+" => s"\\1***"
+```jldoctest hvp3; filter = r"([0-9]+\.[0-9]{8})[0-9]+" => s"\1***"
 julia> f(x) = sin(x[1] * x[2]);
 
 julia> res = Vector{Float64}(undef, 2);