Documentation updates

[mikeingold]

Changed

• Replaced the previous Example Usage page with a new Tutorial page.
• Replaced /docs/src/index.md with a symlink to /README.md for consistency.
• Updated the Support Matrix (relabeled and reordered columns) and notes.
• Added new pages: Integration Rules, Tips.
• Organized the "Developer Notes" Markdown files into a new sub-directory.

Will close #23

Documenter preview: https://juliageometry.github.io/MeshIntegrals.jl/previews/PR165/

[github-actions]

Benchmark Results

	main	6a428ec...	main/6a428ec49a3aeb...
Differentials/Differential	0.203 ± 0.001 μs	0.202 ± 0.001 μs	1
Differentials/Jacobian	0.168 ± 0.001 μs	0.167 ± 0.0001 μs	1
Integrals/Segment/Scalar GaussKronrod	0.829 ± 0.007 μs	0.829 ± 0.01 μs	1
Integrals/Segment/Scalar GaussLegendre	1.61 ± 0.01 μs	1.68 ± 0.0061 μs	0.961
Integrals/Segment/Scalar HAdaptiveCubature	1.06 ± 0.1 μs	1.04 ± 0.1 μs	1.02
Integrals/Segment/Vector GaussKronrod	3.05 ± 0.076 μs	3.01 ± 0.06 μs	1.01
Integrals/Segment/Vector GaussLegendre	17.5 ± 0.52 μs	17.3 ± 0.52 μs	1.01
Integrals/Segment/Vector HAdaptiveCubature	3.94 ± 0.1 μs	3.91 ± 0.096 μs	1.01
Integrals/Sphere/Scalar GaussKronrod	0.0731 ± 0.0018 ms	0.0733 ± 0.0019 ms	0.997
Integrals/Sphere/Scalar GaussLegendre	1.83 ± 0.0029 ms	1.82 ± 0.0041 ms	1
Integrals/Sphere/Scalar HAdaptiveCubature	0.0473 ± 0.00017 ms	0.0472 ± 0.00013 ms	1
Integrals/Sphere/Vector GaussKronrod	0.11 ± 0.0015 ms	0.107 ± 0.0014 ms	1.02
Integrals/Sphere/Vector GaussLegendre	3.26 ± 0.098 ms	3.26 ± 0.089 ms	0.998
Integrals/Sphere/Vector HAdaptiveCubature	0.0992 ± 0.0014 ms	0.0989 ± 0.0016 ms	1
Rules/GaussLegendre	21.8 ± 0.65 μs	21.8 ± 0.5 μs	1
Specializations/Scalar GaussLegendre/BezierCurve	0.252 ± 0.0061 ms	0.252 ± 0.0035 ms	0.999
Specializations/Scalar GaussLegendre/Line	7.14 ± 0.088 μs	7 ± 0.072 μs	1.02
Specializations/Scalar GaussLegendre/Plane	0.747 ± 0.0015 ms	0.747 ± 0.0015 ms	1
Specializations/Scalar GaussLegendre/Ray	5.99 ± 0.065 μs	5.9 ± 0.057 μs	1.02
Specializations/Scalar GaussLegendre/Rope	0.0515 ± 0.00027 ms	0.0508 ± 0.00031 ms	1.01
Specializations/Scalar GaussLegendre/Tetrahedron	0.157 ± 0.0017 s	0.156 ± 0.00092 s	1.01
Specializations/Scalar GaussLegendre/Triangle	0.602 ± 0.0071 ms	0.603 ± 0.0074 ms	0.998
time_to_load	1.55 ± 0.037 s	1.51 ± 0.0041 s	1.03

Benchmark Plots

A plot of the benchmark results have been uploaded as an artifact to the workflow run for this PR.
Go to "Actions"->"Benchmark a pull request"->[the most recent run]->"Artifacts" (at the bottom).

[mikeingold]

Work still in progress, but I'm open to feedback on what I've written so far.

[JoshuaLampert]

This looks already quite nice. Thanks!
I left some small suggestions below.

[JoshuaLampert]

We also need to add Meshes.jl and Unitful.jl to https://github.com/JuliaGeometry/MeshIntegrals.jl/blob/main/docs/Project.toml.

[JoshuaLampert]

Hm, Documenter.jl errors instead of showing the error if there is an error thrown within an @example block.

[JoshuaLampert]

Hm, Documenter.jl errors instead of showing the error if there is an error thrown within an @example block.

Maybe we could put these in a separate julia block?

[mikeingold]

If the labels cross-over between @example and jldoctest we use that instead, but I don't think printing the entire error message for each call is really desirable here.

[mikeingold]

Trying a jldoctest now with the same label. Apparently you don't have to print the entire error string; it matches on the beginning of the produced error.

[JoshuaLampert]

Looks like the jldoctest doesn't recognize the code from the other @example blocks even though they have the same label. We could also make everything a jldocstest, maybe?

[mikeingold]

Since this block is kind of an outlier and fairly simple, I think I'm just going to convert it back to a static julia.

[JoshuaLampert]

What might be interesting and worth mentioning is that using AD via Enzyme also speeds up the computation significantly. I believe, this is due to the fact that with AD we are exact and the relative tolerance is reached (much) earlier:

julia> using Enzyme

julia> @btime integral(f, segment, GaussKronrod())
  1.006 μs (7 allocations: 480 bytes)
0.0 m N

[mikeingold]

This is a really interesting counter-example, actually. In this case it seems like maybe quadgk is struggling to meet the required tolerances because the finite-difference differential is just noisy enough to be a problem.

I think I'll do some re-wording to move away from the causal connection to exactly-zero-solutions, and just refer to the general phenomena that sometimes it can surprisingly struggle to close on a solution, in which case providing explicit setting tolerances can be beneficial.