Use @autodocs to dynamically include all docstrings (#123)

* use autodocs to dynamically include all docstrings

* add section for specializations

* add some links and crossreferences

* unify docstrings for BezierCurve spezialization

* add link and fix typo

Author: JoshuaLampert

docs/make.jl

@@ -1,6 +1,12 @@
 using Documenter
 using MeshIntegrals
 
+# Dynamically set all files in subdirectories of the source directory to include all files in these subdirectories.
+# This way they don't need to be listed explicitly.
+SPECIALIZATIONS_FILES = joinpath.(Ref("specializations"),
+    readdir(joinpath(dirname(@__DIR__), "src",
+        "specializations")))
+
 makedocs(
     sitename = "MeshIntegrals.jl",
     pages = [

docs/src/api.md

@@ -1,29 +1,40 @@
 # Public API
 
+```@meta
+CurrentModule = MeshIntegrals
+```
+
 ## Integrals
 
-```@docs
-MeshIntegrals.integral
+```@autodocs
+Modules = [MeshIntegrals]
+Pages = ["integral.jl"]
+```
+
+### Specializations
+
+```@autodocs
+Modules = [MeshIntegrals]
+Pages = Main.SPECIALIZATIONS_FILES
 ```
 
 ### Aliases
 
-```@docs
-MeshIntegrals.lineintegral
-MeshIntegrals.surfaceintegral
-MeshIntegrals.volumeintegral
+```@autodocs
+Modules = [MeshIntegrals]
+Pages = ["integral_aliases.jl"]
 ```
 
 ## Integration Rules
 
-```@docs
-MeshIntegrals.GaussKronrod
-MeshIntegrals.GaussLegendre
-MeshIntegrals.HAdaptiveCubature
+```@autodocs
+Modules = [MeshIntegrals]
+Pages = ["integration_rules.jl"]
 ```
 
 ## Derivatives
 
-```@docs
-MeshIntegrals.jacobian
+```@autodocs
+Modules = [MeshIntegrals]
+Pages = ["differentiation.jl"]
 ```

docs/src/supportmatrix.md

@@ -1,7 +1,7 @@
 # Support Matrix
 
-While this library aims to support all possible integration rules and **Meshes.jl**
-geometry types, some combinations are ill-suited and some others are simplu not yet
+While this library aims to support all possible integration rules and [**Meshes.jl**](https://github.com/JuliaGeometry/Meshes.jl)
+geometry types, some combinations are ill-suited and some others are simply not yet
 implemented. The following Support Matrix aims to capture the current development state of
 all geometry/rule combinations. Entries with a green check mark are fully supported
 and have passing unit tests that provide some confidence they produce accurate results.

src/integral_aliases.jl

@@ -10,9 +10,9 @@ using a particular numerical integration `rule` with floating point precision of
 type `FP`.
 
 Rule types available:
-- GaussKronrod (default)
-- GaussLegendre
-- HAdaptiveCubature
+- [`GaussKronrod`](@ref) (default)
+- [`GaussLegendre`](@ref)
+- [`HAdaptiveCubature`](@ref)
 """
 function lineintegral(
         f::Function,
@@ -42,9 +42,9 @@ using a particular numerical integration `rule` with floating point precision of
 type `FP`.
 
 Algorithm types available:
-- GaussKronrod
-- GaussLegendre
-- HAdaptiveCubature (default)
+- [`GaussKronrod`](@ref)
+- [`GaussLegendre`](@ref)
+- [`HAdaptiveCubature`](@ref) (default)
 """
 function surfaceintegral(
         f::Function,
@@ -74,9 +74,9 @@ Numerically integrate a given function `f(::Point)` throughout a volumetric
 precision of type `FP`.
 
 Algorithm types available:
-- GaussKronrod
-- GaussLegendre
-- HAdaptiveCubature (default)
+- [`GaussKronrod`](@ref)
+- [`GaussLegendre`](@ref)
+- [`HAdaptiveCubature`](@ref) (default)
 """
 function volumeintegral(
         f::Function,

src/integration_rules.jl

@@ -7,7 +7,8 @@ abstract type IntegrationRule end
 """
     GaussKronrod(kwargs...)
 
-The h-adaptive Gauss-Kronrod quadrature rule implemented by QuadGK.jl. All standard
+The h-adaptive Gauss-Kronrod quadrature rule implemented by
+[QuadGK.jl](https://github.com/JuliaMath/QuadGK.jl). All standard
 `QuadGK.quadgk` keyword arguments are supported. This rule works natively for one
 dimensional geometries; some two- and three-dimensional geometries are additionally
 supported using nested integral solvers with the specified `kwarg` settings.
@@ -21,7 +22,8 @@ end
     GaussLegendre(n)
 
 An `n`'th-order Gauss-Legendre quadrature rule. Nodes and weights are
-efficiently calculated using FastGaussQuadrature.jl.
+efficiently calculated using
+[FastGaussQuadrature.jl](https://github.com/JuliaApproximation/FastGaussQuadrature.jl).
 
 So long as the integrand function can be well-approximated by a polynomial of
 order `2n-1`, this method should yield results with 16-digit accuracy in `O(n)`
@@ -36,7 +38,8 @@ end
 """
     HAdaptiveCubature(kwargs...)
 
-The h-adaptive cubature rule implemented by HCubature.jl. All standard
+The h-adaptive cubature rule implemented by
+[HCubature.jl](https://github.com/JuliaMath/HCubature.jl). All standard
 `HCubature.hcubature` keyword arguments are supported.
 """
 struct HAdaptiveCubature <: IntegrationRule

src/specializations/BezierCurve.jl

@@ -10,7 +10,7 @@
 ################################################################################
 
 """
-    integral(f, curve::BezierCurve, ::GaussLegendre;
+    integral(f, curve::BezierCurve, rule = GaussKronrod();
              FP=Float64, alg=Meshes.Horner())
 
 Like [`integral`](@ref) but integrates along the domain defined a `curve`. By
@@ -39,17 +39,6 @@ function integral(
     return FP(1 // 2) * sum(w .* integrand(x) for (w, x) in zip(ws, xs))
 end
 
-"""
-    integral(f, curve::BezierCurve, ::GaussKronrod;
-             FP=Float64, alg=Meshes.Horner())
-
-Like [`integral`](@ref) but integrates along the domain defined a `curve`. By
-default this uses Horner's method to improve performance when parameterizing
-the `curve` at the expense of a small loss of precision. Additional accuracy
-can be obtained by specifying the use of DeCasteljau's algorithm instead with
-`alg=Meshes.DeCasteljau()` but can come at a steep cost in memory allocations,
-especially for curves with a large number of control points.
-"""
 function integral(
         f::F,
         curve::Meshes.BezierCurve,
@@ -62,17 +51,6 @@ function integral(
     return QuadGK.quadgk(integrand, zero(FP), one(FP); rule.kwargs...)[1]
 end
 
-"""
-    integral(f, curve::BezierCurve, ::HAdaptiveCubature;
-             FP=Float64, alg=Meshes.Horner())
-
-Like [`integral`](@ref) but integrates along the domain defined a `curve`. By
-default this uses Horner's method to improve performance when parameterizing
-the `curve` at the expense of a small loss of precision. Additional accuracy
-can be obtained by specifying the use of DeCasteljau's algorithm instead with
-`alg=Meshes.DeCasteljau()` but can come at a steep cost in memory allocations,
-especially for curves with a large number of control points.
-"""
 function integral(
         f::F,
         curve::Meshes.BezierCurve,