Add FAQ section to docs

[gdalle]

EDIT: see full extend of the PR below #1343 (comment)

Fix #1329 by adding a note to the Duplicated docstring

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 75.37%. Comparing base (2f6d564) to head (1868b58).
Report is 7 commits behind head on main.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1343      +/-   ##
==========================================
+ Coverage   75.19%   75.37%   +0.17%     
==========================================
  Files          35       35              
  Lines       10669    10672       +3     
==========================================
+ Hits         8023     8044      +21     
+ Misses       2646     2628      -18     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[gdalle]

I used the opportunity to restructure a bit, as mentioned in #1344

The Duplicated explanation is now part of a broader "FAQ" page, which also contains the former end of the home page and the pullback stuff.

I switched the order of the tutorials to put the basic one first, and renamed it accordingly.

[gdalle]

Hopefully the build works, it failed locally due to dependency shenanigans (similar to #1189)

guillaume Enzyme.jl ±|gd/duplicated_same ✗|→ julia --project=docs -e '
    using Pkg
    Pkg.develop(path="lib/EnzymeCore")
    Pkg.develop(path="lib/EnzymeTestUtils")
    Pkg.develop(PackageSpec(path=pwd()))
    Pkg.instantiate()
    include("docs/make.jl")
'
   Resolving package versions...
    Updating `~/Work/GitHub/Julia/Enzyme.jl/docs/Project.toml`
⌅ [e30172f5] + Documenter v0.27.25
  [f151be2c] + EnzymeCore v0.7.0 `../lib/EnzymeCore`
  [98b081ad] + Literate v2.16.1
    Updating `~/Work/GitHub/Julia/Enzyme.jl/docs/Manifest.toml`
  [a4c015fc] + ANSIColoredPrinters v0.0.1
  [ffbed154] + DocStringExtensions v0.9.3
⌅ [e30172f5] + Documenter v0.27.25
  [f151be2c] + EnzymeCore v0.7.0 `../lib/EnzymeCore`
  [b5f81e59] + IOCapture v0.2.4
  [682c06a0] + JSON v0.21.4
  [98b081ad] + Literate v2.16.1
  [69de0a69] + Parsers v2.8.1
  [aea7be01] + PrecompileTools v1.2.1
  [21216c6a] + Preferences v1.4.3
  [56f22d72] + Artifacts
  [2a0f44e3] + Base64
  [ade2ca70] + Dates
  [b77e0a4c] + InteractiveUtils
  [76f85450] + LibGit2
  [8f399da3] + Libdl
  [56ddb016] + Logging
  [d6f4376e] + Markdown
  [a63ad114] + Mmap
  [ca575930] + NetworkOptions v1.2.0
  [de0858da] + Printf
  [3fa0cd96] + REPL
  [9a3f8284] + Random
  [ea8e919c] + SHA v0.7.0
  [9e88b42a] + Serialization
  [6462fe0b] + Sockets
  [fa267f1f] + TOML v1.0.3
  [8dfed614] + Test
  [cf7118a7] + UUIDs
  [4ec0a83e] + Unicode
  [e37daf67] + LibGit2_jll v1.6.4+0
  [29816b5a] + LibSSH2_jll v1.11.0+1
  [c8ffd9c3] + MbedTLS_jll v2.28.2+1
        Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated -m`
   Resolving package versions...
ERROR: Unsatisfiable requirements detected for package Enzyme [7da242da]:
 Enzyme [7da242da] log:
 ├─possible versions are: 0.1.0-0.11.20 or uninstalled
 ├─restricted to versions 0.11-0.12 by EnzymeTestUtils [12d8515a], leaving only versions: 0.11.0-0.11.20
 │ └─EnzymeTestUtils [12d8515a] log:
 │   ├─possible versions are: 0.1.5 or uninstalled
 │   └─EnzymeTestUtils [12d8515a] is fixed to version 0.1.5
 └─restricted by compatibility requirements with EnzymeCore [f151be2c] to versions: 0.1.0-0.10.9 or uninstalled — no versions left
   └─EnzymeCore [f151be2c] log:
     ├─possible versions are: 0.7.0 or uninstalled
     └─EnzymeCore [f151be2c] is fixed to version 0.7.0
Stacktrace:
  [1] propagate_constraints!(graph::Pkg.Resolve.Graph, sources::Set{Int64}; log_events::Bool)
    @ Pkg.Resolve ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Resolve/graphtype.jl:1072
  [2] propagate_constraints! (repeats 2 times)
    @ ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Resolve/graphtype.jl:1008 [inlined]
  [3] simplify_graph!(graph::Pkg.Resolve.Graph, sources::Set{Int64}; clean_graph::Bool)
    @ Pkg.Resolve ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Resolve/graphtype.jl:1533
  [4] simplify_graph! (repeats 2 times)
    @ ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Resolve/graphtype.jl:1532 [inlined]
  [5] resolve_versions!(env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, julia_version::VersionNumber, installed_only::Bool)
    @ Pkg.Operations ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Operations.jl:407
  [6] targeted_resolve(env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, preserve::Pkg.Types.PreserveLevel, julia_version::VersionNumber)
    @ Pkg.Operations ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Operations.jl:1360
  [7] tiered_resolve(env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, julia_version::VersionNumber, try_all_installed::Bool)
    @ Pkg.Operations ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Operations.jl:1349
  [8] _resolve(io::Base.TTY, env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, preserve::Pkg.Types.PreserveLevel, julia_version::VersionNumber)
    @ Pkg.Operations ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Operations.jl:1370
  [9] develop(ctx::Pkg.Types.Context, pkgs::Vector{Pkg.Types.PackageSpec}, new_git::Set{Base.UUID}; preserve::Pkg.Types.PreserveLevel, platform::Base.BinaryPlatforms.Platform)
    @ Pkg.Operations ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Operations.jl:1410
 [10] develop
    @ ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/Operations.jl:1402 [inlined]
 [11] develop(ctx::Pkg.Types.Context, pkgs::Vector{Pkg.Types.PackageSpec}; shared::Bool, preserve::Pkg.Types.PreserveLevel, platform::Base.BinaryPlatforms.Platform, kwargs::@Kwargs{io::Base.TTY})
    @ Pkg.API ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/API.jl:225
 [12] develop(pkgs::Vector{Pkg.Types.PackageSpec}; io::Base.TTY, kwargs::@Kwargs{})
    @ Pkg.API ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/API.jl:159
 [13] develop(pkgs::Vector{Pkg.Types.PackageSpec})
    @ Pkg.API ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/API.jl:148
 [14] develop
    @ ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/API.jl:146 [inlined]
 [15] develop(; name::Nothing, uuid::Nothing, version::Nothing, url::Nothing, rev::Nothing, path::String, mode::Pkg.Types.PackageMode, subdir::Nothing, kwargs::@Kwargs{})
    @ Pkg.API ~/.julia/juliaup/julia-1.10.2+0.x64.linux.gnu/share/julia/stdlib/v1.10/Pkg/src/API.jl:176
 [16] top-level scope
    @ none:4

[gdalle]

Documentation passes, the rest is not on me

[gdalle]

I updated the link to the section of the docs (#1343 (comment)), for me this seems good to go

[wsmoses]

I think a couple more are missing like

Enzyme.jl/src/Enzyme.jl

Line 267 in 778deec

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."))

and

Enzyme.jl/src/compiler.jl

Line 516 in 778deec

throw(AssertionError(string(T)*" has mixed internal activity types. See https://enzyme.mit.edu/julia/dev/#Mixed-Activity for more information"))

[gdalle]

going to bed now, it's 11 in Switzerland ;) will pick it up tomorrow with your remarks! thanks for helping me out on this

[wsmoses]

going to bed now, it's 11 in Switzerland ;) will pick it up tomorrow with your remarks! thanks for helping me out on this

And thank you so much for working on this! Hopefully together we can make this easier for folks to use/understand!

[wsmoses]

Perhaps in another follow up PR, but @gdalle can I distract you further into helping digest https://discourse.julialang.org/t/how-do-you-speed-up-the-linear-sparse-solver-in-zygote/111801/36?u=wsmoses into additional and accessible docs?

[gdalle]

I put the advanced details @wsmoses suggested to add in a separate issue #1355

Since this PR is first and foremost about moving stuff around (see #1344), I suggest we merge it and come back to the content at a later time. This would get rid of the current (huge) diff, and allow us to focus on more narrow modifications next.
What do you think?

[andrinr]

Would it not be possible to check weather x or dx (or both) are views and then not raise the error? I'm fairly new to Julia, but I assume using a view is oftentimes a best practice. Especially when using an iterative solver, where the entire history of forward results of x need to be stored.