Formatting of the docs

README.md

@@ -15,60 +15,59 @@
   <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/479ff0c6-3c65-44fe-b3e0-2ed653e7e3a5" alt="TrixiP_logo" width="40%"/>
 </p>
 
-**TrixiParticles.jl** is a high-performance numerical simulation framework for particle-based methods, focused on the simulation of complex multiphysics problems, and written in [Julia](https://julialang.org).
+**TrixiParticles.jl** is a high-performance simulation framework for particle-based methods for complex multiphysics applications, written in [Julia](https://julialang.org).
 
 TrixiParticles.jl focuses on the following use cases:
-- Accurate and efficient physics-based modelling of complex multiphysics problems.
+- Accurate and efficient physics-based modeling of complex multiphysics problems.
 - Development of new particle-based methods and models.
-- Easy setup of accessible simulations for educational purposes, including student projects, coursework, and thesis work.
+- Accessible simulation setup for educational purposes, including student projects, coursework, and thesis work.
 
-It offers intuitive configuration, robust pre- and post-processing, and vendor-agnostic GPU-support based on the Julia package [KernelAbstractions.jl](https://github.com/JuliaGPU/KernelAbstractions.jl).
+It offers intuitive configuration, robust pre- and post-processing, and vendor-agnostic GPU support based on the Julia package [KernelAbstractions.jl](https://github.com/JuliaGPU/KernelAbstractions.jl).
 
 [![YouTube](https://github.com/user-attachments/assets/dc2be627-a799-4bfd-9226-2077f737c4b0)](https://www.youtube.com/watch?v=V7FWl4YumcA&t=4667s)
 
 ## Features
-- Incompressible Navier-Stokes
-  - Methods: Weakly Compressible Smoothed Particle Hydrodynamics (WCSPH),
-    Entropically Damped Artificial Compressibility (EDAC),
-    Implicit Incompressible SPH (IISPH)
+- Incompressible Navier-Stokes flows
+  - Methods: Weakly Compressible Smoothed Particle Hydrodynamics (WCSPH), Entropically Damped Artificial Compressibility (EDAC),
+    Implicit Incompressible Smoothed Particle Hydrodynamics (IISPH)
   - Models: Surface Tension, Open Boundaries
-- Solid-body mechanics
-  - Methods:  Total Lagrangian SPH (TLSPH), Discrete Element Method (DEM)
+- Structural mechanics
+  - Methods: Total Lagrangian SPH (TLSPH), Discrete Element Method (DEM)
 - Fluid-Structure Interaction
-- Particle sampling of complex geometries from `.stl` and `.asc` files.
+- Particle sampling of complex geometries from `.stl`, `.asc`, and `.dxf` files.
 - Output formats:
   - VTK
-- Support for GPUs by Nvidia, AMD and Apple (experimental)
+- GPU support for NVIDIA, AMD, and Apple devices
 
 ## Examples
 We provide several example simulation setups in the `examples` folder (which can be accessed from Julia via `examples_dir()`).
 
 <table align="center" border="0">
-  <tr>
-  </tr>
   <tr>
     <td align="center">
-      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/683e9363-5705-49cc-9a5c-3b47d73ea4b8" style="width: 80% !important;"/><br><figcaption>2D Dam Break</figcaption>
+      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/683e9363-5705-49cc-9a5c-3b47d73ea4b8" style="width: 80% !important;"/><br />
+      <figcaption>2D Dam Break</figcaption>
     </td>
     <td align="center">
-      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/c10faddf-0400-47c9-b225-f5d286a8ecb8" style="width: 80% !important;"/><br><figcaption>Moving Wall</figcaption>
+      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/c10faddf-0400-47c9-b225-f5d286a8ecb8" style="width: 80% !important;"/><br />
+      <figcaption>Moving Wall</figcaption>
     </td>
   </tr>
-  <tr>
-  </tr>
   <tr>
     <td align="center">
-      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/e05ace63-e330-441a-a391-eda3d2764074" style="width: 80% !important;"/><br><figcaption>Oscillating Beam</figcaption>
+      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/e05ace63-e330-441a-a391-eda3d2764074" style="width: 80% !important;"/><br />
+      <figcaption>Oscillating Beam</figcaption>
     </td>
     <td align="center">
-      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/ada0d554-e0ba-44ed-923d-2b77ef252258" style="width: 80% !important;"/><br><figcaption>Dam Break with Elastic Plate</figcaption>
+      <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/ada0d554-e0ba-44ed-923d-2b77ef252258" style="width: 80% !important;"/><br />
+      <figcaption>Dam Break with Elastic Plate</figcaption>
     </td>
   </tr>
 </table>
 
 
 ## Installation
-If you have not yet installed Julia, please [follow the instructions for your
+If you have not installed Julia yet, please [follow the instructions for your
 operating system](https://julialang.org/downloads/platform/). TrixiParticles.jl works
 with Julia v1.10 and newer. We recommend using the latest stable release of Julia.
 
@@ -115,7 +114,12 @@ Then start the simulation by executing
 julia> trixi_include(joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"))
 ```
 
-This will open a new window with a 2D visualization of the final solution:
+To visualize the result quickly, use Plots.jl:
+```julia
+julia> using Plots; plot(sol)
+```
+
+This opens a new window with a 2D visualization of the final solution:
 <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/44124897/95821154-577d-4323-ba57-16ef02ea24e0" width="400">
 
 Further details can be found in the [documentation](https://trixi-framework.github.io/TrixiParticles.jl/stable).
@@ -160,7 +164,7 @@ and
 
 ## Authors
 Erik Faulhaber (University of Cologne) and Niklas Neher (HLRS) implemented the foundations
-for TrixiParticles.jl and are principal developers along with Sven Berger (hereon).
+for TrixiParticles.jl and are principal developers along with Sven Berger (Hereon).
 The project was started by Michael Schlottke-Lakemper (University of Augsburg)
 and Gregor Gassner (University of Cologne), who provide scientific direction and technical advice.
 The full list of contributors can be found in [AUTHORS.md](AUTHORS.md).
@@ -183,4 +187,3 @@ or [create an issue](https://github.com/trixi-framework/TrixiParticles.jl/issues
 </p>
 
 The project has benefited from funding from [hereon](https://www.hereon.de/), [HiRSE](https://www.helmholtz-hirse.de/), and through [ScienceServe](https://www.helmholtz.de/en/research/current-calls-for-applications/article/scienceserve-boosting-research-software-at-helmholtz/) for the MATRIX project.
-

docs/src/development.md

@@ -1,68 +1,67 @@
 # [Development](@id development)
 
+## Preview of the Documentation
 
-## Preview of the documentation
-
-To generate the Documentation, first instantiate the `docs` environment
-by executing the following command from the TrixiParticles.jl root directory:
+To build the documentation, first instantiate the `docs` environment by running the
+following command from the TrixiParticles.jl root directory:
 ```bash
 julia --project=docs -e "using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()"
 ```
-This command only has to be run once. After that, maintain the `docs` environment
+You only need to run this command once. After that, maintain the `docs` environment
 as described under [Installation](@ref installation-issues).
 
-With an instantiated `docs` environment, generate the docs with the following command (again from the TrixiParticles.jl root directory):
+Once the `docs` environment is instantiated, build the documentation with the following
+command (again from the TrixiParticles.jl root directory):
 ```bash
 julia --project=docs --color=yes docs/make.jl
 ```
-You can then open the generated files in `docs/build` with your webbrowser.
+You can then open the generated files in `docs/build` in your web browser.
 Alternatively, run
 ```bash
 python3 -m http.server -d docs/build
 ```
-and open `localhost:8000` in your webbrowser.
+and open `localhost:8000` in your web browser.
 
 
-## Release management
+## Release Management
 
 To create a new release for TrixiParticles.jl, perform the following steps:
-1) Make sure that all PRs and changes that you want to go into the release are merged to
+1. Make sure that all PRs and changes that you want to go into the release are merged to
    `main` and that the latest commit on `main` has passed all CI tests.
-2) Determine the currently released version of TrixiParticles.jl, e.g., on the
+2. Determine the currently released version of TrixiParticles.jl, e.g., on the
    [release page](https://github.com/trixi-framework/TrixiParticles.jl/releases). For this manual,
    we will assume that the latest release was `v0.2.3`.
-3) Decide on the next version number. We follow [semantic versioning](https://semver.org/),
+3. Decide on the next version number. We follow [semantic versioning](https://semver.org/),
    thus each version is of the form `vX.Y.Z` where `X` is the major version, `Y` the minor
    version, and `Z` the patch version. In this manual, we assume that the major version is
    always `0`, thus the decision process on the new version is as follows:
-   * If the new release contains *breaking changes* (i.e., user code might not work as
+   - If the new release contains *breaking changes* (i.e., user code might not work as
      before without modifications), increase the *minor* version by one and set the
      *patch* version to zero. In our example, the new version should thus be `v0.3.0`.
-   * If the new release only contains minor modifications and/or bug fixes, the *minor*
+   - If the new release only contains minor modifications and/or bug fixes, the *minor*
      version is kept as-is and the *patch* version is increased by one. In our example, the
      new version should thus be `v0.2.4`.
-4) Edit the `version` string in the
+4. Edit the `version` string in the
    [`Project.toml`](https://github.com/trixi-framework/TrixiParticles.jl/blob/main/Project.toml)
    and set it to the new version. Push/merge this change to `main`.
-5) Go to GitHub and add a comment to the commit that you would like to become the new
+5. Go to GitHub and add a comment to the commit that you would like to become the new
    release (typically this will be the commit where you just updated the version). You can
    comment on a commit by going to the
    [commit overview](https://github.com/trixi-framework/TrixiParticles.jl/commits/main/) and clicking
    on the title of the commit. The comment should contain the following text:
    ```
    @JuliaRegistrator register
    ```
-6) Wait for the magic to happen! Specifically, JuliaRegistrator will create a new PR to the
+6. Wait for the magic to happen. Specifically, JuliaRegistrator will create a new PR to the
    Julia registry with the new release information. After a grace period of ~15 minutes,
    this PR will be merged automatically. A short while after,
    [TagBot](https://github.com/trixi-framework/TrixiParticles.jl/blob/main/.github/workflows/TagBot.yml)
    will create a new release of TrixiParticles.jl in our GitHub repository.
-7) Once the new release has been created, the new version can be obtained through the Julia
+7. Once the new release has been created, the new version can be obtained through the Julia
    package manager as usual.
-8) To make sure people do not mistake the latest state of `main` as the latest release, we
+8. To make sure people do not mistake the latest state of `main` as the latest release, we
    set the version in the `Project.toml` to a *development* version. The development version
    should be the latest released version, with the patch version incremented by one, and the
    `-dev` suffix added. For example, if you just released `v0.3.0`, the new development
    version should be `v0.3.1-dev`. If you just released `v0.2.4`, the new development
    version should be `v0.2.5-dev`.
-

docs/src/examples.md

@@ -42,7 +42,7 @@
 <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/f9a542bf-956b-4647-843b-94cbb085a4fa" width="60%"/>
 ```
 
-## Fluid Structure Interaction
+## Fluid-Structure Interaction
 
 ### Dam Break with Elastic Plate (`fsi/dam_break_plate_2d.jl`)
 ```@raw html
@@ -59,7 +59,7 @@
 <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/b3964f68-2782-43e6-b6ff-be96f9f224ae" width="60%"/>
 ```
 
-## Structure Mechanics
+## Structural Mechanics
 
 ### Oscillating Beam (`solid/oscillating_beam_2d.jl`)
 ```@raw html

docs/src/general/neighborhood_search.md

@@ -1,13 +1,14 @@
 # Neighborhood Search
 
-The neighborhood search is the most essential component for performance.
+The neighborhood search is one of the most performance-critical components.
 We provide several implementations in the package
 [PointNeighbors.jl](https://github.com/trixi-framework/PointNeighbors.jl).
-See the docs of this package for an overview and a comparison of different implementations.
+See the PointNeighbors.jl documentation for an overview and a comparison of the
+different implementations.
 
 !!! note "Usage"
-    To run a simulation with a neighborhood search implementation, pass a template of the
-    neighborhood search to the constructor of the [`Semidiscretization`](@ref).
+    To run a simulation with a neighborhood search implementation, pass a neighborhood
+    search template to the constructor of the [`Semidiscretization`](@ref).
     A template is just an empty neighborhood search with search radius `0.0`.
     See [`copy_neighborhood_search`](@ref) and the examples below for more details.
     ```jldoctest semi_example; output=false, setup = :(using TrixiParticles; trixi_include(@__MODULE__, joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"), sol=nothing); system1 = fluid_system; system2 = boundary_system)

docs/src/getting_started.md

@@ -1,14 +1,15 @@
-# [Getting started](@id getting_started)
-If you have not installed TrixiParticles.jl, please follow the instructions given [here](install.md).
+# [Getting Started](@id getting_started)
 
-In the following sections, we will give a short introduction. For a more thorough discussion, take a look at our [Tutorials](tutorial.md).
+If you have not installed TrixiParticles.jl yet, please follow the instructions in [Installation](@ref installation).
+
+This page provides a short introduction. For a broader introduction, take a look at our [Tutorials](tutorial.md).
 
 ## Running an Example
-The easiest way to run a simulation is to run one of our predefined example files.
+The easiest way to start is to run one of the predefined example files.
 We will run the file `examples/fluid/hydrostatic_water_column_2d.jl`, which simulates a fluid resting in a rectangular tank.
 Since TrixiParticles.jl uses multithreading, you should start Julia with the flag `--threads auto` (or, e.g. `--threads 4` for 4 threads).
 
-In the Julia REPL, first load the package TrixiParticles.jl.
+In the Julia REPL, first load `TrixiParticles.jl`.
 ```jldoctest getting_started
 julia> using TrixiParticles
 ```
@@ -28,28 +29,28 @@ This will open a new window with a 2D visualization of the final solution:
 
 For more information about visualization, see [Visualization](visualization.md).
 
-## Running other Examples
-You can find a list of our other predefined examples under [Examples](examples.md).
-Execute them as follows from the Julia REPL by replacing `subfolder` and `example_name`
+## Running Other Examples
+You can find more predefined examples under [Examples](examples.md).
+Run them from the Julia REPL by replacing `subfolder` and `example_name`:
 ```julia
 julia> trixi_include(joinpath(examples_dir(), "subfolder", "example_name.jl"))
 ```
 
-## Modifying an example
+## Modifying an Example
 You can pass keyword arguments to the function `trixi_include` to overwrite assignments in the file.
 
-With `trixi_include`, we can overwrite variables defined in the example file to run a different simulation without modifying the example file.
+With `trixi_include`, we can overwrite variables defined in the example file to run a different simulation without modifying the file itself.
 ```jldoctest getting_started; filter = r".*"s
 julia> trixi_include(joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"), initial_fluid_size=(1.0, 0.5))
 ```
-This for example, will change the fluid size from ``(0.9, 1.0)`` to ``(1.0, 0.5)``.
+This, for example, changes the fluid size from ``(0.9, 1.0)`` to ``(1.0, 0.5)``.
 
-To understand why, take a look into the file `hydrostatic_water_column_2d.jl` in the subfolder `fluid` inside the examples directory, which is the file that we executed earlier.
+To understand why, take a look at the file `hydrostatic_water_column_2d.jl` in the `fluid` subdirectory of the examples directory, which is the file we executed earlier.
 You can see that the initial size of the fluid is defined in the variable `initial_fluid_size`, which we could overwrite with the `trixi_include` call above.
 Another variable that is worth experimenting with is `fluid_particle_spacing`, which controls the resolution of the simulation in this case.
 A lower value will increase the resolution and the runtime.
 
-## Set up you first simulation from scratch
+## Set Up Your First Simulation from Scratch
 See [Set up your first simulation](tutorials/tut_setup.md).
 
-Find an overview over the available tutorials under [Tutorials](tutorial.md).
+An overview of the available tutorials is available under [Tutorials](tutorial.md).