Cross references with DocumenterInterLinks (#33)

* Setup DocumenterInterLinks * fix external links to Trixi.jl * fix cross references for the mlswe --------- Co-authored-by: Andrew Winters <[email protected]>
trixi-framework · Apr 4, 2024 · a76d1ba · a76d1ba
1 parent 43caf4f
commit a76d1ba
Show file tree

Hide file tree

Showing 10 changed files with 40 additions and 34 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,6 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 TrixiShallowWater = "804cb1fc-5b08-4398-a671-a789bfe091b3"
 
 [compat]
-Documenter = "0.27"
+Documenter = "1.3"
+DocumenterInterLinks = "0.3.1"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,5 +1,10 @@
 using TrixiShallowWater
 using Documenter
+using DocumenterInterLinks
+
+# Provide external links to the Trixi.jl docs (project root and inventory file)
+links = InterLinks("Trixi" => ("https://trixi-framework.github.io/Trixi.jl/stable/",
+                               "https://trixi-framework.github.io/Trixi.jl/stable/objects.inv"))
 
 DocMeta.setdocmeta!(TrixiShallowWater, :DocTestSetup, :(using TrixiShallowWater);
                     recursive = true)
@@ -16,7 +21,8 @@ makedocs(;
                                   assets = String[],),
          pages = [
              "Home" => "index.md",
-         ],)
+         ],
+         plugins = [links],)
 
 deploydocs(;
            repo = "github.com/trixi-framework/TrixiShallowWater.jl",

diff --git a/src/callbacks_stage/positivity_shallow_water.jl b/src/callbacks_stage/positivity_shallow_water.jl
@@ -15,7 +15,7 @@ or the [`ShallowWaterEquationsWetDry2D`](@ref) struct to determine the minimal a
 The order of the `variables` is important and might have a strong influence
 on the robustness.
 
-As opposed to the standard version of the [`PositivityPreservingLimiterZhangShu`](@ref),
+As opposed to the standard version of the [`Trixi.PositivityPreservingLimiterZhangShu`](@extref),
 nodes with a water height below the `threshold_limiter` are treated in a special way.
 To avoid numerical problems caused by velocities close to zero,
 the velocity is cut off, such that the node can be identified as "dry". The special feature of the

diff --git a/src/equations/numerical_fluxes.jl b/src/equations/numerical_fluxes.jl
@@ -17,7 +17,7 @@ function min_max_speed_chen_noelle end
 """
     flux_hll_chen_noelle = FluxHLL(min_max_speed_chen_noelle)
 
-An instance of [`FluxHLL`](@ref) specific to the shallow water equations that
+An instance of [`Trixi.FluxHLL`](@extref) specific to the shallow water equations that
 uses the wave speed estimates from [`min_max_speed_chen_noelle`](@ref).
 This HLL flux is guaranteed to have zero numerical mass flux out of a "dry" element,
 maintain positivity of the water height, and satisfy an entropy inequality.

diff --git a/src/equations/shallow_water_multilayer_1d.jl b/src/equations/shallow_water_multilayer_1d.jl
@@ -41,7 +41,7 @@ This affects the implementation and use of these equations in various ways:
 * The flux values corresponding to the bottom topography must be zero.
 * The bottom topography values must be included when defining initial conditions, boundary
   conditions or source terms.
-* [`AnalysisCallback`](@ref) analyzes this variable.
+* [`Trixi.AnalysisCallback`](@extref) analyzes this variable.
 * Trixi's visualization tools will visualize the bottom topography by default.
 
 A good introduction for the MLSWE is available in Chapter 12 of the book:
@@ -50,7 +50,6 @@ A good introduction for the MLSWE is available in Chapter 12 of the book:
       <https://www.sciencedirect.com/bookseries/international-geophysics/vol/101/suppl/C>\
       ISBN: 978-0-12-088759-0
 """
-
 struct ShallowWaterMultiLayerEquations1D{NVARS, NLAYERS, RealT <: Real} <:
        AbstractShallowWaterMultiLayerEquations{1, NVARS, NLAYERS}
     gravity::RealT   # gravitational constant
@@ -128,7 +127,7 @@ end
 
 A smooth initial condition for a three-layer configuration used for convergence tests in combination with
 [`source_terms_convergence_test`](@ref) (and
-[`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref) in non-periodic domains).
+[`Trixi.BoundaryConditionDirichlet`](@extref) in non-periodic domains).
 """
 function Trixi.initial_condition_convergence_test(x, t,
                                                   equations::ShallowWaterMultiLayerEquations1D)
@@ -156,7 +155,7 @@ end
 
 Source terms used for convergence tests with a three-layer configuration in combination with
 [`initial_condition_convergence_test`](@ref)
-(and [`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref)
+(and [`Trixi.BoundaryConditionDirichlet`](@extref)
 in non-periodic domains).
 """
 @inline function Trixi.source_terms_convergence_test(u, x, t,
@@ -316,7 +315,7 @@ When the bottom topography is nonzero this scheme will be well-balanced when use
 nonconservative [`flux_nonconservative_ersing_etal`](@ref).
 
 To obtain an entropy stable formulation the `surface_flux` can be set as
-[`FluxPlusDissipation(flux_ersing_etal, DissipationLocalLaxFriedrichs()), flux_nonconservative_ersing_etal`](@ref).
+`FluxPlusDissipation(flux_ersing_etal, DissipationLocalLaxFriedrichs()), flux_nonconservative_ersing_etal`.
 
 In the two-layer setting this combination is equivalent to the fluxes in:
 - Patrick Ersing, Andrew R. Winters (2023)

diff --git a/src/equations/shallow_water_two_layer_1d.jl b/src/equations/shallow_water_two_layer_1d.jl
@@ -49,7 +49,7 @@ This affects the implementation and use of these equations in various ways:
 * The flux values corresponding to the bottom topography must be zero.
 * The bottom topography values must be included when defining initial conditions, boundary
   conditions or source terms.
-* [`AnalysisCallback`](@ref) analyzes this variable.
+* [`Trixi.AnalysisCallback`](@extref) analyzes this variable.
 * Trixi's visualization tools will visualize the bottom topography by default.
 
 A good introduction for the 2LSWE is available in Chapter 12 of the book:
@@ -102,7 +102,7 @@ end
 
 A smooth initial condition used for convergence tests in combination with
 [`source_terms_convergence_test`](@ref) (and
-[`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref) in non-periodic domains).
+[`Trixi.BoundaryConditionDirichlet`](@extref) in non-periodic domains).
 """
 function Trixi.initial_condition_convergence_test(x, t,
                                                   equations::ShallowWaterTwoLayerEquations1D)
@@ -123,7 +123,7 @@ end
 
 Source terms used for convergence tests in combination with
 [`initial_condition_convergence_test`](@ref)
-(and [`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref)
+(and [`Trixi.BoundaryConditionDirichlet`](@extref)
 in non-periodic domains).
 """
 @inline function Trixi.source_terms_convergence_test(u, x, t,

diff --git a/src/equations/shallow_water_two_layer_2d.jl b/src/equations/shallow_water_two_layer_2d.jl
@@ -63,7 +63,7 @@ This affects the implementation and use of these equations in various ways:
 * The flux values corresponding to the bottom topography must be zero.
 * The bottom topography values must be included when defining initial conditions, boundary
   conditions or source terms.
-* [`AnalysisCallback`](@ref) analyzes this variable.
+* [`Trixi.AnalysisCallback`](@extref) analyzes this variable.
 * Trixi's visualization tools will visualize the bottom topography by default.
 
 A good introduction for the 2LSWE is available in Chapter 12 of the book:

diff --git a/src/equations/shallow_water_wet_dry_1d.jl b/src/equations/shallow_water_wet_dry_1d.jl
@@ -42,7 +42,7 @@ This affects the implementation and use of these equations in various ways:
 * The flux values corresponding to the bottom topography must be zero.
 * The bottom topography values must be included when defining initial conditions, boundary conditions or
   source terms.
-* [`AnalysisCallback`](@ref) analyzes this variable.
+* [`Trixi.AnalysisCallback`](@extref) analyzes this variable.
 * Trixi.jl's visualization tools will visualize the bottom topography by default.
 
 References for the SWE are many but a good introduction is available in Chapter 13 of the book:
@@ -111,9 +111,8 @@ end
 
 A smooth initial condition used for convergence tests in combination with
 [`source_terms_convergence_test`](@ref)
-(and [`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref) in non-periodic domains).
+(and [`Trixi.BoundaryConditionDirichlet`](@extref) in non-periodic domains).
 """
-
 function Trixi.initial_condition_convergence_test(x, t,
                                                   equations::ShallowWaterEquationsWetDry1D)
     return Trixi.initial_condition_convergence_test(x, t,
@@ -125,7 +124,7 @@ end
 
 Source terms used for convergence tests in combination with
 [`initial_condition_convergence_test`](@ref)
-(and [`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref) in non-periodic domains).
+(and [`Trixi.BoundaryConditionDirichlet`](@extref) in non-periodic domains).
 
 This manufactured solution source term is specifically designed for the bottom topography function
 `b(x) = 2.0 + 0.5 * sin(sqrt(2.0)*pi*x[1])`
@@ -250,12 +249,12 @@ end
                                       equations::ShallowWaterEquationsWetDry1D)
 
 Non-symmetric two-point surface flux that discretizes the nonconservative (source) term.
-The discretization uses the `hydrostatic_reconstruction_audusse_etal` on the conservative
+The discretization uses the [`hydrostatic_reconstruction_audusse_etal`](@ref) on the conservative
 variables.
 
 This hydrostatic reconstruction ensures that the finite volume numerical fluxes remain
 well-balanced for discontinuous bottom topographies [`ShallowWaterEquationsWetDry1D`](@ref).
-Should be used together with [`FluxHydrostaticReconstruction`](@ref) and
+Should be used together with [`Trixi.FluxHydrostaticReconstruction`](@extref) and
 [`hydrostatic_reconstruction_audusse_etal`](@ref) in the surface flux to ensure consistency.
 
 Further details on the hydrostatic reconstruction and its motivation can be found in
@@ -277,10 +276,10 @@ end
                                      equations::ShallowWaterEquationsWetDry1D)
 
 Non-symmetric two-point surface flux that discretizes the nonconservative (source) term.
-The discretization uses the `hydrostatic_reconstruction_chen_noelle` on the conservative
+The discretization uses the [`hydrostatic_reconstruction_chen_noelle`](@ref) on the conservative
 variables.
 
-Should be used together with [`FluxHydrostaticReconstruction`](@ref) and
+Should be used together with [`Trixi.FluxHydrostaticReconstruction`](@extref) and
 [`hydrostatic_reconstruction_chen_noelle`](@ref) in the surface flux to ensure consistency.
 
 Further details on the hydrostatic reconstruction and its motivation can be found in
@@ -388,7 +387,7 @@ end
 A particular type of hydrostatic reconstruction on the water height to guarantee well-balancedness
 for a general bottom topography [`ShallowWaterEquationsWetDry1D`](@ref). The reconstructed solution states
 `u_ll_star` and `u_rr_star` variables are then used to evaluate the surface numerical flux at the interface.
-Use in combination with the generic numerical flux routine [`FluxHydrostaticReconstruction`](@ref).
+Use in combination with the generic numerical flux routine [`Trixi.FluxHydrostaticReconstruction`](@extref).
 
 Further details on this hydrostatic reconstruction and its motivation can be found in
 - Emmanuel Audusse, François Bouchut, Marie-Odile Bristeau, Rupert Klein, and Benoit Perthame (2004)
@@ -409,7 +408,7 @@ A particular type of hydrostatic reconstruction of the water height to guarantee
 for a general bottom topography of the [`ShallowWaterEquationsWetDry1D`](@ref). The reconstructed solution states
 `u_ll_star` and `u_rr_star` variables are used to evaluate the surface numerical flux at the interface.
 The key idea is a linear reconstruction of the bottom and water height at the interfaces using subcells.
-Use in combination with the generic numerical flux routine [`FluxHydrostaticReconstruction`](@ref).
+Use in combination with the generic numerical flux routine [`Trixi.FluxHydrostaticReconstruction`](@extref).
 
 Further details on this hydrostatic reconstruction and its motivation can be found in
 - Guoxian Chen and Sebastian Noelle (2017)

diff --git a/src/equations/shallow_water_wet_dry_2d.jl b/src/equations/shallow_water_wet_dry_2d.jl
@@ -45,7 +45,7 @@ This affects the implementation and use of these equations in various ways:
 * The flux values corresponding to the bottom topography must be zero.
 * The bottom topography values must be included when defining initial conditions, boundary conditions or
   source terms.
-* [`AnalysisCallback`](@ref) analyzes this variable.
+* [`Trixi.AnalysisCallback`](@extref) analyzes this variable.
 * Trixi.jl's visualization tools will visualize the bottom topography by default.
 
 References for the SWE are many but a good introduction is available in Chapter 13 of the book:
@@ -112,7 +112,7 @@ Trixi.varnames(::typeof(cons2prim), ::ShallowWaterEquationsWetDry2D) = ("H", "v1
 
 A smooth initial condition used for convergence tests in combination with
 [`source_terms_convergence_test`](@ref)
-(and [`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref) in non-periodic domains).
+(and [`Trixi.BoundaryConditionDirichlet`](@extref) in non-periodic domains).
 """
 function Trixi.initial_condition_convergence_test(x, t,
                                                   equations::ShallowWaterEquationsWetDry2D)
@@ -125,7 +125,7 @@ end
 
 Source terms used for convergence tests in combination with
 [`initial_condition_convergence_test`](@ref)
-(and [`BoundaryConditionDirichlet(initial_condition_convergence_test)`](@ref) in non-periodic domains).
+(and [`Trixi.BoundaryConditionDirichlet`](@extref) in non-periodic domains).
 
 This manufactured solution source term is specifically designed for the bottom topography function
 `b(x,y) = 2 + 0.5 * sin(sqrt(2)*pi*x) + 0.5 * sin(sqrt(2)*pi*y)`
@@ -188,7 +188,7 @@ end
     boundary_condition_slip_wall(u_inner, orientation, direction, x, t,
                                  surface_flux_function, equations::ShallowWaterEquationsWetDry2D)
 
-Should be used together with [`TreeMesh`](@ref).
+Should be used together with [`Trixi.TreeMesh`](@extref).
 """
 @inline function Trixi.boundary_condition_slip_wall(u_inner, orientation,
                                                     direction, x, t,
@@ -321,7 +321,7 @@ end
 A particular type of hydrostatic reconstruction on the water height to guarantee well-balancedness
 for a general bottom topography [`ShallowWaterEquationsWetDry2D`](@ref). The reconstructed solution states
 `u_ll_star` and `u_rr_star` variables are used to evaluate the surface numerical flux at the interface.
-Use in combination with the generic numerical flux routine [`FluxHydrostaticReconstruction`](@ref).
+Use in combination with the generic numerical flux routine [`Trixi.FluxHydrostaticReconstruction`](@extref).
 
 Further details for the hydrostatic reconstruction and its motivation can be found in
 - Emmanuel Audusse, François Bouchut, Marie-Odile Bristeau, Rupert Klein, and Benoit Perthame (2004)
@@ -342,7 +342,7 @@ A particular type of hydrostatic reconstruction of the water height to guarantee
 for a general bottom topography of the [`ShallowWaterEquationsWetDry2D`](@ref). The reconstructed solution states
 `u_ll_star` and `u_rr_star` variables are then used to evaluate the surface numerical flux at the interface.
 The key idea is a linear reconstruction of the bottom and water height at the interfaces using subcells.
-Use in combination with the generic numerical flux routine [`FluxHydrostaticReconstruction`](@ref).
+Use in combination with the generic numerical flux routine [`Trixi.FluxHydrostaticReconstruction`](@extref).
 
 Further details on this hydrostatic reconstruction and its motivation can be found in
 - Guoxian Chen and Sebastian Noelle (2017)
@@ -405,12 +405,12 @@ end
                                       equations::ShallowWaterEquationsWetDry2D)
 
 Non-symmetric two-point surface flux that discretizes the nonconservative (source) term.
-The discretization uses the `hydrostatic_reconstruction_audusse_etal` on the conservative
+The discretization uses the [`hydrostatic_reconstruction_audusse_etal`](@ref) on the conservative
 variables.
 
 This hydrostatic reconstruction ensures that the finite volume numerical fluxes remain
 well-balanced for discontinuous bottom topographies [`ShallowWaterEquationsWetDry2D`](@ref).
-Should be used together with [`FluxHydrostaticReconstruction`](@ref) and
+Should be used together with [`Trixi.FluxHydrostaticReconstruction`](@extref) and
 [`hydrostatic_reconstruction_audusse_etal`](@ref) in the surface flux to ensure consistency.
 
 Further details for the hydrostatic reconstruction and its motivation can be found in
@@ -448,7 +448,7 @@ Non-symmetric two-point surface flux that discretizes the nonconservative (sourc
 The discretization uses the [`hydrostatic_reconstruction_chen_noelle`](@ref) on the conservative
 variables.
 
-Should be used together with [`FluxHydrostaticReconstruction`](@ref) and
+Should be used together with [`Trixi.FluxHydrostaticReconstruction`](@extref) and
 [`hydrostatic_reconstruction_chen_noelle`](@ref) in the surface flux to ensure consistency.
 
 Further details on the hydrostatic reconstruction and its motivation can be found in

diff --git a/src/solvers/indicators.jl b/src/solvers/indicators.jl
@@ -12,14 +12,14 @@
                                           alpha_smooth=true,
                                           variable)
 
-Modified version of the [`IndicatorHennemannGassner`](@ref)
+Modified version of the [`Trixi.IndicatorHennemannGassner`](@extref)
 indicator used for shock-capturing for shallow water equations. After
 the element-wise values for the blending factors are computed an additional check
 is made to see if the element is partially wet. In this case, partially wet elements
 are set to use the pure finite volume scheme that is guaranteed to be well-balanced
 for this wet/dry transition state of the flow regime.
 
-See also [`VolumeIntegralShockCapturingHG`](@ref).
+See also [`Trixi.VolumeIntegralShockCapturingHG`](@extref).
 
 ## References