From 450cc1de7b4691af6d673e8dea36889365ff4f77 Mon Sep 17 00:00:00 2001
From: Michael Ingold <mike.ingold@gmail.com>
Date: Tue, 3 Sep 2024 22:33:58 -0400
Subject: [PATCH] Improve documentation (#62)

* Update Support Matrix page

* Add page for algorithms

* Add page for example usage

* Remove support matrix from README
---
 README.md                 | 39 -------------------
 docs/make.jl              |  4 +-
 docs/src/algorithms.md    | 19 ++++++++++
 docs/src/supportmatrix.md | 79 +++++++++++++++++++++++----------------
 docs/src/usage.md         | 31 +++++++++++++++
 5 files changed, 99 insertions(+), 73 deletions(-)
 create mode 100644 docs/src/algorithms.md
 create mode 100644 docs/src/usage.md

diff --git a/README.md b/README.md
index ed1f8612..e14a058f 100644
--- a/README.md
+++ b/README.md
@@ -48,42 +48,3 @@ integral(f, unit_circle_bz, GaussKronrod())
     # 0.017122 seconds (18.93 k allocations: 78.402 MiB)
     # ans = 5.551055333711397 m^2
 ```
-
-# Support Matrix
-
-| Symbol | Meaning |
-|--------|---------|
-| :white_check_mark: | Implemented, passes tests |
-| :x: | Not yet supported |
-| :stop_sign: | Not supported |
-
-### Integral
-| Geometry | Gauss-Legendre | Gauss-Kronrod | H-Adaptive Cubature |
-|----------|----------------|---------------|---------------------|
-| `Ball` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Ball` in `𝔼{3}` | :white_check_mark: | :stop_sign: | :white_check_mark: |
-| `BezierCurve` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Box` in `𝔼{1}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Box` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Box` in `𝔼{3}` | :white_check_mark: | :stop_sign: | :white_check_mark: |
-| `Circle` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Cone` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `ConeSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Cylinder` | :white_check_mark: | :stop_sign: | :white_check_mark: |
-| `CylinderSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Disk` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Frustum` | :stop_sign: | :stop_sign: | :stop_sign: |
-| `FrustumSurface` | :stop_sign: | :stop_sign: | :stop_sign: |
-| `Line` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `ParaboloidSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Plane` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Ray` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Ring` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Rope` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Segment` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `SimpleMesh` | :x: | :x: | :x: |
-| `Sphere` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Sphere` in `𝔼{3}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Tetrahedron` in `𝔼{3}` | :x: | :white_check_mark: | :x: |
-| `Triangle` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Torus` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
diff --git a/docs/make.jl b/docs/make.jl
index 1db76bac..e77747ee 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -6,7 +6,9 @@ makedocs(
     pages = [
         "Home" => [
             "About" => "index.md",
-            "Support Matrix" => "supportmatrix.md"
+            "Support Matrix" => "supportmatrix.md",
+            "Integration Algorithms" => "algorithms.md",
+            "Example Usage" => "usage.md"
         ],
         "Derivations" => [
             "Integrating a Triangle" => "triangle.md"
diff --git a/docs/src/algorithms.md b/docs/src/algorithms.md
new file mode 100644
index 00000000..45209400
--- /dev/null
+++ b/docs/src/algorithms.md
@@ -0,0 +1,19 @@
+# Integration Algorithms
+
+## Gauss-Kronrod
+
+```@docs
+MeshIntegrals.GaussKronrod
+```
+
+## Gauss-Legendre
+
+```@docs
+MeshIntegrals.GaussLegendre
+```
+
+## H-Adaptive Cubature
+
+```@docs
+MeshIntegrals.HAdaptiveCubature
+```
\ No newline at end of file
diff --git a/docs/src/supportmatrix.md b/docs/src/supportmatrix.md
index 53e1d487..2afddd81 100644
--- a/docs/src/supportmatrix.md
+++ b/docs/src/supportmatrix.md
@@ -1,38 +1,51 @@
 # Support Matrix
 
-| Symbol | Meaning |
+While this library aims to support all possible integration algorithms and **Meshes.jl**
+geometry types, some combinations are ill-suited and some others are simplu not yet
+implemented. The following Support Matrix aims to capture the current development state of
+all geometry/algorithm combinations. Entries with a green check mark are fully supported
+and have passing unit tests that provide some confidence they produce accurate results.
+
+In general, Gauss-Kronrod integration rules are recommended (and the default) for geometries
+with one parametric dimension, e.g.: `Segment`, `BezierCurve`, and `Rope`. Gauss-Kronrod
+rules can also be applied to some geometries with more dimensions by nesting multiple
+integration solves, but this is inefficient. These Gauss-Kronrod rules are supported (but
+not recommended) for surface-like geometries, but not for volume-like geometries. For
+geometries with more than one parametric dimension, e.g. surfaces and volumes, H-Adaptive
+Cubature integration rules are recommended (and the default).
+
+| Symbol | Support Level |
 |--------|---------|
-| :white_check_mark: | Implemented, passes tests |
-| :x: | Not yet supported |
-| :stop_sign: | Not supported |
+| ✅ | Supported, passes unit tests |
+| 🎗️ | Planned to support in the future |
+| 🛑 | Not supported |
 
-### Integral
-| Geometry | Gauss-Legendre | Gauss-Kronrod | H-Adaptive Cubature |
+| `Meshes.Geometry` | Gauss-Legendre | Gauss-Kronrod | H-Adaptive Cubature |
 |----------|----------------|---------------|---------------------|
-| `Ball` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Ball` in `𝔼{3}` | :white_check_mark: | :stop_sign: | :white_check_mark: |
-| `BezierCurve` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Box` in `𝔼{1}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Box` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Box` in `𝔼{3}` | :white_check_mark: | :stop_sign: | :white_check_mark: |
-| `Circle` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Cone` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `ConeSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Cylinder` | :white_check_mark: | :stop_sign: | :white_check_mark: |
-| `CylinderSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Disk` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Frustum` | :stop_sign: | :stop_sign: | :stop_sign: |
-| `FrustumSurface` | :stop_sign: | :stop_sign: | :stop_sign: |
-| `Line` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `ParaboloidSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Plane` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Ray` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Ring` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Rope` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Segment` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `SimpleMesh` | :x: | :x: | :x: |
-| `Sphere` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Sphere` in `𝔼{3}` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Tetrahedron` in `𝔼{3}` | :x: | :white_check_mark: | :x: |
-| `Triangle` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| `Torus` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| `Ball` in `𝔼{2}` | ✅ | ✅ | ✅ |
+| `Ball` in `𝔼{3}` | ✅ | 🛑 | ✅ |
+| `BezierCurve` | ✅ | ✅ | ✅ |
+| `Box` in `𝔼{1}` | ✅ | ✅ | ✅ |
+| `Box` in `𝔼{2}` | ✅ | ✅ | ✅ |
+| `Box` in `𝔼{3}` | ✅ | 🛑 | ✅ |
+| `Circle` | ✅ | ✅ | ✅ |
+| `Cone` | ✅ | ✅ | ✅ |
+| `ConeSurface` | ✅ | ✅ | ✅ |
+| `Cylinder` | ✅ | 🛑 | ✅ |
+| `CylinderSurface` | ✅ | ✅ | ✅ |
+| `Disk` | ✅ | ✅ | ✅ |
+| `Frustum` | 🛑 | 🛑 | 🛑 |
+| `FrustumSurface` | 🛑 | 🛑 | 🛑 |
+| `Line` | ✅ | ✅ | ✅ |
+| `ParaboloidSurface` | ✅ | ✅ | ✅ |
+| `Plane` | ✅ | ✅ | ✅ |
+| `Ray` | ✅ | ✅ | ✅ |
+| `Ring` | ✅ | ✅ | ✅ |
+| `Rope` | ✅ | ✅ | ✅ |
+| `Segment` | ✅ | ✅ | ✅ |
+| `SimpleMesh` | 🎗️ | 🎗️ | 🎗️ |
+| `Sphere` in `𝔼{2}` | ✅ | ✅ | ✅ |
+| `Sphere` in `𝔼{3}` | ✅ | ✅ | ✅ |
+| `Tetrahedron` in `𝔼{3}` | 🎗️ | ✅ | 🎗️ |
+| `Triangle` | ✅ | ✅ | ✅ |
+| `Torus` | ✅ | ✅ | ✅ |
diff --git a/docs/src/usage.md b/docs/src/usage.md
new file mode 100644
index 00000000..d731b754
--- /dev/null
+++ b/docs/src/usage.md
@@ -0,0 +1,31 @@
+# Example Usage
+
+## Integrating along a Bezier curve
+
+```julia
+using Meshes
+using MeshIntegrals
+
+# Define a unit circle on the xy-plane
+origin = Point(0,0,0)
+ẑ = Vec(0,0,1)
+xy_plane = Plane(origin,ẑ)
+unit_circle_xy = Circle(xy_plane, 1.0)
+
+# Approximate unit_circle_xy with a high-order Bezier curve
+unit_circle_bz = BezierCurve(
+    [Point(cos(t), sin(t), 0.0) for t in range(0,2pi,length=361)]
+)
+
+# A Real-valued function
+f(x, y, z) = abs(x + y)
+f(p) = f(to(p)...)
+
+integral(f, unit_circle_xy, GaussKronrod())
+    # 0.000170 seconds (5.00 k allocations: 213.531 KiB)
+    # ans == 5.656854249525293 m^2
+
+integral(f, unit_circle_bz, GaussKronrod())
+    # 0.017122 seconds (18.93 k allocations: 78.402 MiB)
+    # ans = 5.551055333711397 m^2
+```
\ No newline at end of file