From b6f871088f6955d9167573027916531649438bb9 Mon Sep 17 00:00:00 2001
From: Erik Faulhaber <44124897+efaulhaber@users.noreply.github.com>
Date: Tue, 17 Oct 2023 07:19:44 +0200
Subject: [PATCH] Fix docs and compile docs in CI (#241)

* Fix docs

* Add docs for `InitialCondition`

* Compile docs automatically in CI

* Fix setup docs

* Fix CI

* Fix CI

* Fix NHS in docs

* Add examples for initial condition
---
 .github/workflows/ci.yml                      |  4 ++
 docs/Project.toml                             |  3 +
 docs/src/index.md                             | 28 +++------
 src/callbacks/density_reinit.jl               |  6 +-
 src/general/initial_condition.jl              | 58 +++++++++++++++++++
 .../dummy_particles/dummy_particles.jl        |  4 +-
 .../state_equations.jl                        |  4 +-
 src/setups/rectangular_shape.jl               |  2 +-
 src/setups/sphere_shape.jl                    | 12 ++--
 9 files changed, 88 insertions(+), 33 deletions(-)
 create mode 100644 docs/Project.toml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4941456b0..a3fc5b857 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -66,6 +66,10 @@ jobs:
           files: lcov.info
           fail_ci_if_error: true
           flags: unit
+      - name: Compile docs
+        run: |
+          julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+          julia --project=docs --color=yes docs/make.jl
       - name: Run example tests
         uses: julia-actions/julia-runtest@v1
         with:
diff --git a/docs/Project.toml b/docs/Project.toml
new file mode 100644
index 000000000..2ca447130
--- /dev/null
+++ b/docs/Project.toml
@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+TrixiParticles = "66699cd8-9c01-4e9d-a059-b96c86d16b3a"
diff --git a/docs/src/index.md b/docs/src/index.md
index a1e9b6518..3387075d2 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -21,12 +21,6 @@ Modules = [TrixiParticles]
 Pages = [joinpath("general", "initial_condition.jl")]
 ```
 
-### File neighborhood_search.jl
-```@autodocs
-Modules = [TrixiParticles]
-Pages = [joinpath("general", "neighborhood_search.jl")]
-```
-
 ### File semidiscretization.jl
 ```@autodocs
 Modules = [TrixiParticles]
@@ -39,6 +33,13 @@ Modules = [TrixiParticles]
 Pages = [joinpath("general", "smoothing_kernels.jl")]
 ```
 
+## Neighborhood Search
+
+```@autodocs
+Modules = [TrixiParticles]
+Pages = map(file -> joinpath("neighborhood_search", file), readdir(joinpath("..", "src", "neighborhood_search")))
+```
+
 ## Schemes
 
 ### Boundary
@@ -104,22 +105,9 @@ Pages = [joinpath("schemes", "solid", "total_lagrangian_sph", "penalty_force.jl"
 
 ## Setups
 
-### File rectangular_tank.jl
-```@autodocs
-Modules = [TrixiParticles]
-Pages = [joinpath("setups", "rectangular_tank.jl")]
-```
-
-### File rectangular_shape.jl
-```@autodocs
-Modules = [TrixiParticles]
-Pages = [joinpath("setups", "rectangular_shape.jl")]
-```
-
-### File circular_shape.jl
 ```@autodocs
 Modules = [TrixiParticles]
-Pages = [joinpath("setups", "circular_shape.jl")]
+Pages = map(file -> joinpath("setups", file), readdir(joinpath("..", "src", "setups")))
 ```
 
 ## Util
diff --git a/src/callbacks/density_reinit.jl b/src/callbacks/density_reinit.jl
index 9f87a2fc0..886d58519 100644
--- a/src/callbacks/density_reinit.jl
+++ b/src/callbacks/density_reinit.jl
@@ -1,7 +1,7 @@
 """
     DensityReinitializationCallback(; interval::Integer=0, dt=0.0)
 
-Callback to reinitialize the density field when using [ContinuityDensity](@ref).
+Callback to reinitialize the density field when using [`ContinuityDensity`](@ref).
 
 # Keywords
 - `interval=0`:              Reinitialize the density every `interval` time steps.
@@ -10,8 +10,8 @@ Callback to reinitialize the density field when using [ContinuityDensity](@ref).
 - `reinit_initial_solution`: Reinitialize the initial solution (default=false)
 ## References:
 - Panizzo, Andrea, Giovanni Cuomo, and Robert A. Dalrymple. "3D-SPH simulation of landslide generated waves."
-    In: Coastal Engineering 2006: (In 5 Volumes). 2007. 1503-1515.
-    [doi:10.1142/9789812709554_0128](https://doi.org/10.1142/9789812709554_0128)
+  In: Coastal Engineering 2006 (2007), pages 1503-1515.
+  [doi: 10.1142/9789812709554_0128](https://doi.org/10.1142/9789812709554_0128)
 """
 mutable struct DensityReinitializationCallback{I}
     interval::I
diff --git a/src/general/initial_condition.jl b/src/general/initial_condition.jl
index 306a08aa1..909ce69c0 100644
--- a/src/general/initial_condition.jl
+++ b/src/general/initial_condition.jl
@@ -1,3 +1,61 @@
+@doc raw"""
+    InitialCondition(coordinates, velocities, masses, densities; pressure=0.0,
+                     particle_spacing=-1.0)
+
+Struct to hold the initial configuration of the particles.
+
+The following setups return `InitialCondition`s for commonly used setups:
+- [`RectangularShape`](@ref)
+- [`SphereShape`](@ref)
+- [`RectangularTank`](@ref)
+
+`InitialCondition`s support the set operations `union`, `setdiff` and `intersect` in order
+to build more complex geometries.
+
+# Arguments
+- `coordinates`: An array where the $i$-th column holds the coordinates of particle $i$.
+- `velocities`: An array where the $i$-th column holds the velocity of particle $i$.
+- `masses`: A vector holding the mass of each particle.
+- `densities`: A vector holding the density of each particle.
+
+# Keywords
+- `pressure`: Either a vector of pressure values of each particle or a number for a constant
+              pressure over all particles. This is optional and only needed when using
+              the [`EntropicallyDampedSPHSystem`](@ref).
+- `particle_spacing`: The spacing between the particles. This is a number, as the spacing
+                      is assumed to be uniform. This is only needed when using
+                      set operations on the `InitialCondition`.
+
+# Examples
+```julia
+# Rectangle filled with particles
+initial_condition = RectangularShape(0.1, (3, 4), (-1.0, 1.0), 1.0)
+
+# Two spheres in one initial condition
+initial_condition = union(SphereShape(0.15, 0.5, (-1.0, 1.0), 1.0),
+                          SphereShape(0.15, 0.2, (0.0, 1.0), 1.0))
+
+# Rectangle with a spherical hole
+shape1 = RectangularShape(0.1, (16, 13), (-0.8, 0.0), 1.0)
+shape2 = SphereShape(0.1, 0.35, (0.0, 0.6), 1.0, sphere_type=RoundSphere())
+initial_condition = setdiff(shape1, shape2)
+
+# Intersect of a rectangle with a sphere. Note that this keeps the particles of the
+# rectangle that are in the intersect, while `intersect(shape2, shape1)` would consist of
+# the particles of the sphere that are in the intersect.
+shape1 = RectangularShape(0.1, (16, 13), (-0.8, 0.0), 1.0)
+shape2 = SphereShape(0.1, 0.35, (0.0, 0.6), 1.0, sphere_type=RoundSphere())
+initial_condition = intersect(shape1, shape2)
+
+# Build `InitialCondition` manually
+coordinates = [0.0 1.0 1.0
+               0.0 0.0 1.0]
+velocities = zero(coordinates)
+masses = ones(3)
+densities = 1000 * ones(3)
+initial_condition = InitialCondition(coordinates, velocities, masses, densities)
+```
+"""
 struct InitialCondition{ELTYPE}
     particle_spacing :: ELTYPE
     coordinates      :: Array{ELTYPE, 2}
diff --git a/src/schemes/boundary/dummy_particles/dummy_particles.jl b/src/schemes/boundary/dummy_particles/dummy_particles.jl
index f9c2b990a..747b55b45 100644
--- a/src/schemes/boundary/dummy_particles/dummy_particles.jl
+++ b/src/schemes/boundary/dummy_particles/dummy_particles.jl
@@ -4,10 +4,10 @@
 
 Boundaries modeled as dummy particles, which are treated like fluid particles,
 but their positions and velocities are not evolved in time. Since the force towards the fluid
-should not change with the material density when used with a `TotalLagrangianSPHSystem`, the
+should not change with the material density when used with a [`TotalLagrangianSPHSystem`](@ref), the
 dummy particles need to have a mass corresponding to the fluid's rest density, which we call
 "hydrodynamic mass", as opposed to mass corresponding to the material density of a
-`TotalLagrangianSPHSystem`.
+[`TotalLagrangianSPHSystem`](@ref).
 
 Here, `initial_density` and `hydrodynamic_mass` are vectors that contains the initial density
 and the hydrodynamic mass respectively for each boundary particle.
diff --git a/src/schemes/fluid/weakly_compressible_sph/state_equations.jl b/src/schemes/fluid/weakly_compressible_sph/state_equations.jl
index 6f5f81627..d230cf7c4 100644
--- a/src/schemes/fluid/weakly_compressible_sph/state_equations.jl
+++ b/src/schemes/fluid/weakly_compressible_sph/state_equations.jl
@@ -11,7 +11,7 @@ where ``c`` denotes the speed of sound, ``\rho`` the density, ``p`` the pressure
 at the reference density, and ``p_{\text{background}}`` the atmospheric or
 background pressure (to be used with free surfaces).
 
-When using [`SummationDensity`](@ref) (or [DensityReinitializationCallback](@ref))
+When using [`SummationDensity`](@ref) (or [`DensityReinitializationCallback`](@ref))
 and free surfaces, initializing particles with equal spacing will cause underestimated
 density and therefore strong attractive forces between particles at the free surface.
 Setting `clip_negative_pressure=true` can avoid this.
@@ -64,7 +64,7 @@ background pressure (to be used with free surfaces).
 
 For water, an average value of ``\gamma = 7.15`` is usually used (Cole 1948, p. 39).
 
-When using [`SummationDensity`](@ref) (or [DensityReinitializationCallback](@ref))
+When using [`SummationDensity`](@ref) (or [`DensityReinitializationCallback`](@ref))
 and free surfaces, initializing particles with equal spacing will cause underestimated
 density and therefore strong attractive forces between particles at the free surface.
 Setting `clip_negative_pressure=true` can avoid this.
diff --git a/src/setups/rectangular_shape.jl b/src/setups/rectangular_shape.jl
index dc63f4592..96c7b053a 100644
--- a/src/setups/rectangular_shape.jl
+++ b/src/setups/rectangular_shape.jl
@@ -13,7 +13,7 @@ Rectangular shape filled with particles. Returns an [`InitialCondition`](@ref).
 - `density`:                            Initial density of particles.
 
 # Keywords
-- `tlsph`:          With the [TotalLagrangianSPHSystem](@ref), particles need to be placed
+- `tlsph`:          With the [`TotalLagrangianSPHSystem`](@ref), particles need to be placed
                     on the boundary of the shape and not one particle radius away, as for fluids.
                     When `tlsph=true`, particles will be placed on the boundary of the shape.
 - `init_velocity`:  The initial velocity of the fluid particles as `(vel_x, vel_y)` (or `(vel_x, vel_y, vel_z)` in 3D).
diff --git a/src/setups/sphere_shape.jl b/src/setups/sphere_shape.jl
index e0e913fba..73a40a376 100644
--- a/src/setups/sphere_shape.jl
+++ b/src/setups/sphere_shape.jl
@@ -34,7 +34,7 @@ coordinate directions as `cutout_min` and `cutout_max`.
                         cut out of the sphere.
 - `cutout_max`:         Corner in positive coordinate directions of a cuboid that is to be
                         cut out of the sphere.
-- `tlsph`:              With the [TotalLagrangianSPHSystem](@ref), particles need to be placed
+- `tlsph`:              With the [`TotalLagrangianSPHSystem`](@ref), particles need to be placed
                         on the boundary of the shape and not one particle radius away, as for fluids.
                         When `tlsph=true`, particles will be placed on the boundary of the shape.
 - `init_velocity`:      Initial velocity vector to be assigned to each particle.
@@ -49,16 +49,13 @@ SphereShape(0.1, 0.5, (0.2, 0.4), 1000.0, sphere_type=RoundSphere())
 
 # Hollow circle with ~3 layers, outer radius 0.5, center in (0.2, 0.4) and a particle
 # spacing of 0.1.
-```julia
 SphereShape(0.1, 0.5, (0.2, 0.4), 1000.0, n_layers=3)
-```
 
 # Same as before, but perfectly round
 SphereShape(0.1, 0.5, (0.2, 0.4), 1000.0, n_layers=3, sphere_type=RoundSphere())
 
 # Hollow circle with 3 layers, inner radius 0.5, center in (0.2, 0.4) and a particle spacing
 # of 0.1.
-```julia
 SphereShape(0.1, 0.5, (0.2, 0.4), 1000.0, n_layers=3, layer_outwards=true)
 
 # Filled circle with radius 0.1, center in (0.0, 0.0), particle spacing 0.1, but the
@@ -71,7 +68,6 @@ SphereShape(0.1, 0.5, (0.2, 0.4, 0.3), 1000.0)
 # Same as before, but perfectly round
 SphereShape(0.1, 0.5, (0.2, 0.4, 0.3), 1000.0, sphere_type=RoundSphere())
 ```
-````
 """
 function SphereShape(particle_spacing, radius, center_position, density;
                      sphere_type=VoxelSphere(), n_layers=-1, layer_outwards=false,
@@ -124,6 +120,9 @@ with a regular inner structure but corners on the surface.
 Essentially, a grid of particles is generated and all particles outside the sphere are removed.
 The resulting sphere will have a perfect inner structure, but is not perfectly round,
 as it will have corners (like a sphere in Minecraft).
+
+!!! note "Usage"
+    See [`SphereShape`](@ref) on how to use this.
 """
 struct VoxelSphere end
 
@@ -132,6 +131,9 @@ struct VoxelSphere end
 
 Construct a sphere by nesting perfectly round concentric spheres.
 The resulting ball will be perfectly round, but will not have a regular inner structure.
+
+!!! note "Usage"
+    See [`SphereShape`](@ref) on how to use this.
 """
 struct RoundSphere end