Add plots and package installation instruction to docs (#449)

* Add installation instructions for users

* Add usage to readme

* Renove failing doctest

* Fix docs

* Add plots

---------

Co-authored-by: Niklas Neher <[email protected]>

README.md

@@ -30,42 +30,67 @@ operating system](https://julialang.org/downloads/platform/). TrixiParticles.jl
 with Julia v1.9 and newer. We recommend using the latest stable release of Julia.
 
 ### For users
-<!--
-TrixiParticles.jl is a registered Julia package. Hence, you
-can install TrixiParticles.jl and OrdinaryDiffEq.jl (used by the examples) by executing the following commands in the Julia REPL:
+TrixiParticles.jl is a registered Julia package.
+You can install TrixiParticles.jl,
+[OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) (used for time integration)
+and [Plots.jl](https://github.com/JuliaPlots/Plots.jl) by executing the following commands
+in the Julia REPL:
 ```julia
 julia> using Pkg
 
-julia> Pkg.add(["OrdinaryDiffEq", "TrixiParticles"])
+julia> Pkg.add(["TrixiParticles", "OrdinaryDiffEq", "Plots"])
 ```
--->
 
 ### For developers
-If you plan on editing TrixiParticles.jl itself, you can download TrixiParticles.jl locally and use the
-code from the cloned directory:
+If you plan on editing TrixiParticles.jl itself, you can download TrixiParticles.jl
+to a local folder and use the code from the cloned directory:
 ```bash
 git clone [email protected]:trixi-framework/TrixiParticles.jl.git
 cd TrixiParticles.jl
 mkdir run
-cd run
-julia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=".."))' # Install locally
-julia --project=. -e 'using Pkg; Pkg.add("OrdinaryDiffEq")' # Install additional packages
+julia --project=run -e 'using Pkg; Pkg.develop(PackageSpec(path="."))' # Add TrixiParticles.jl to `run` project
+julia --project=run -e 'using Pkg; Pkg.add("OrdinaryDiffEq", "Plots")' # Add additional packages
 ```
-**Note:** OrdinaryDiffEq is only necessary to run examples.
 
-If you installed TrixiParticles.jl this way, you always have to start Julia with the `--project`
-flag set to your `run` directory, e.g.,
+If you installed TrixiParticles.jl this way, you always have to start Julia with the
+`--project` flag set to your `run` directory, e.g.,
 ```bash
-julia --project=.
+julia --project=run
 ```
+from the TrixiParticles.jl root directory.
+Further details can be found in the [documentation](@ref installation).
+
+## Usage
+
+In the Julia REPL, first load the package TrixiParticles.jl.
+```jldoctest getting_started
+julia> using TrixiParticles
+```
+
+Then start the simulation by executing
+```jldoctest getting_started; filter = r".*"s
+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:
+<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](@ref getting_started).
+
 ## Documentation
 
+You can find the documentation for the latest release
+[here](https://trixi-framework.github.io/TrixiParticles.jl/stable).
+
 ## Publications
 
 ## Cite Us
 
 ## 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). The project was started by Michael Schlottke-Lakemper (RWTH Aachen University/HLRS) and Gregor Gassner (University of Cologne), who provide scientific direction and technical advice.
+Erik Faulhaber (University of Cologne) and Niklas Neher (HLRS) implemented the foundations
+for TrixiParticles.jl and are principal developers along with Sven Berger (hereon).
+The project was started by Michael Schlottke-Lakemper (RWTH Aachen University/HLRS)
+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).
 
 ## License and contributing

docs/src/getting_started.md

@@ -1,4 +1,4 @@
-# Getting started
+# [Getting started](@id getting_started)
 If you have not installed TrixiParticles.jl, please follow the instructions given [here](install.md).
 
 In the following sections, we will give a short introduction. For a more thorough discussion, take a look at our [Tutorials](tutorial.md).
@@ -9,7 +9,6 @@ We will run the file `examples/fluid/hydrostatic_water_column_2d.jl`, which simu
 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.
-
 ```jldoctest getting_started
 julia> using TrixiParticles
 ```
@@ -19,11 +18,10 @@ Then start the simulation by executing
 julia> trixi_include(joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"))
 ```
 
-This will result in the following:
-![image](https://github.com/svchb/TrixiParticles.jl/assets/10238714/f8d2c249-fd52-4958-bc8b-265bbadc49f2)
-
+This will open a new window with a 2D visualization of the final solution:
+![plot_hydrostatic_water_column](https://github.com/trixi-framework/TrixiParticles.jl/assets/44124897/95821154-577d-4323-ba57-16ef02ea24e0)
 
-To visualize the results, see [Visualization](visualization.md).
+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).

docs/src/index.md

@@ -15,10 +15,10 @@ TrixiParticles.jl is a numerical simulation framework designed for particle-base
 
 
 ## Quickstart
-1. [Installation](@ref)
-2. [Getting started](@ref)
+1. [Installation](@ref installation)
+2. [Getting started](@ref getting_started)
 
 
 ## Start with development
-1. [Installation](@ref)
-2. [Contributing](@ref)
+1. [Installation](@ref installation)
+2. [Contributing](@ref)

docs/src/install.md

@@ -1,26 +1,35 @@
-# Installation
+# [Installation](@id installation)
 
 ## Setting up Julia
 If you have not yet installed Julia, please [follow the instructions for your
 operating system](https://julialang.org/downloads/platform/). TrixiParticles.jl works
 with Julia v1.9 and newer. We recommend using the latest stable release of Julia.
 
-## Installation for users
+## For users
+TrixiParticles.jl is a registered Julia package.
+You can install TrixiParticles.jl,
+[OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) (used for time integration)
+and [Plots.jl](https://github.com/JuliaPlots/Plots.jl) by executing the following commands
+in the Julia REPL:
+```julia
+julia> using Pkg
 
+julia> Pkg.add(["TrixiParticles", "OrdinaryDiffEq", "Plots"])
+```
 
-## [Installation for developers](@id for-developers)
-If you plan on editing TrixiParticles.jl itself, you can download TrixiParticles.jl to a local folder and use the
-code from the cloned directory:
+## [For developers](@id for-developers)
+If you plan on editing TrixiParticles.jl itself, you can download TrixiParticles.jl
+to a local folder and use the code from the cloned directory:
 ```bash
 git clone [email protected]:trixi-framework/TrixiParticles.jl.git
 cd TrixiParticles.jl
 mkdir run
-julia --project=run -e 'using Pkg; Pkg.develop(PackageSpec(path="."))' # Install locally
-julia --project=run -e 'using Pkg; Pkg.add("OrdinaryDiffEq")' # Add TrixiParticles.jl to `run` project
+julia --project=run -e 'using Pkg; Pkg.develop(PackageSpec(path="."))' # Add TrixiParticles.jl to `run` project
+julia --project=run -e 'using Pkg; Pkg.add("OrdinaryDiffEq", "Plots")' # Add additional packages
 ```
 
-If you installed TrixiParticles.jl this way, you always have to start Julia with the `--project`
-flag set to your `run` directory, e.g.,
+If you installed TrixiParticles.jl this way, you always have to start Julia with the
+`--project` flag set to your `run` directory, e.g.,
 ```bash
 julia --project=run
 ```