Module-level documentation and 'Quick start' section.

docs/make.jl

@@ -24,8 +24,9 @@ makedocs(;
         assets = String[],
     ),
     pages = [
-        "Home" => "index.md",
-        "Manual" => [
+        "Welcome" => "index.md",
+        "Guide" => [
+            "Quick start" => "man/quickstart.md",
             "Generate food webs" => "man/foodwebs.md",
             "Generate multiplex networks" => "man/multiplexnetworks.md",
             "Generate model parameters" => "man/modelparameters.md",
@@ -34,7 +35,7 @@ makedocs(;
             "Boost simulations" => "man/boost.md",
             "Measure stability" => "man/stability.md",
         ],
-        "Examples" => [
+        "Tutorials" => [
             "Paradox of enrichment" => "example/paradox_enrichment.md",
             "Intraspecific competition and stability" => "example/intracomp_stability.md",
         ],

docs/src/index.md

@@ -2,51 +2,69 @@
 CurrentModule = EcologicalNetworksDynamics
 ```
 
-# EcologicalNetworkDynamics
+# EcologicalNetworksDynamics
 
-!!! warning "Work in progress"
-
-    🚧🚧🚧
-
-This package provides tools to easily simulate ecological network dynamics using Julia.
+EcologicalNetworksDynamics is a library designed to simulate species biomass dynamics
+in ecological networks.
 These networks can either trophic interactions only (i.e. food webs),
 or trophic interactions plus various non-trophic interactions (i.e. multiplex networks).
 We provide functions to generate food web structure from well-known models
 (e.g. niche model).
-Default community parameters are taken from the literature,
-but can also be easily customized if desired.
+We designed EcologicalNetworksDynamics so that
+it is easy to use for non-specialists
+while remaining flexible for more adventurous and experienced users
+who would like to tweak the model.
+
+## Before you start
 
-!!! note "Todo"
-    
-    Complete the package description and explain in more detail the package features and the
-    package "philosophy".
+Before anything else, to use EcologicalNetworksDynamics you have to install Julia.
+For that go to the [official download page](https://julialang.org/downloads/).
+Once you have successfully installed Julia,
+you can install the library by running from a Julia REPL:
 
-## References
+```julia
+using Pkg
+Pkg.add("EcologicalNetworksDynamics")
+```
 
-  - [Delmas et al., 2016, MEE](https://doi.org/10.1111/2041-210X.12713) -
-    Simulations of biomass dynamics in community food webs
-  - [Miele et al., 2019, PLOS](https://doi.org/10.1371/journal.pcbi.1007269) -
-    Effect of non-trophic interactions on diversity-productivity relationship
-  - [Kefi et al. 2018, Ecology Letters](https://doi.org/10.1111/j.1461-0248.2011.01732.x) -
-    More than a meal... integrating non-feeding interactions into food webs
+To check that the package installation went well,
+you can create a simple food web with:
+
+```julia
+using EcologicalNetworkDynamics
+FoodWeb([1 => 2])
+```
 
-!!! note "Todo"
-
-    Add other references.
+## Learning EcologicalNetworkDynamics
+
+The [Quick start](@ref) page shows how to simulate biomass dynamics in a simple food web.
+The rest of the guide provides a step by step introduction to the package features,
+from the generation of the network structure to the simulation of the biomass dynamics.
+At each step, we detail how the model can be customized at your will.
+Lastly, the Tutorials section contains
+realistic use-cases of EcologicalNetworksDynamics.
+
+## Getting help
+
+During your journey learning EcologicalNetworksDynamics you might encounter issues.
+If so the best is to open an issue on the
+[GitHub page of EcologicalNetworksDynamics](https://github.com/BecksLab/EcologicalNetworksDynamics.jl/issues).
+To ensure that we can help you efficiently,
+please provide a short description of your problem
+and a minimal example to reproduce the error you encountered.
 
 ## How can I contribute?
 
-The easiest way to contribute is to [open an issue](https://github.com/BecksLab/EcologicalNetworksDynamics.jl/issues)
+The easiest way to contribute is to
+[open an issue](https://github.com/BecksLab/EcologicalNetworksDynamics.jl/issues)
 if you spot a bug, a typo or can't manage to do something.
 Another way is to fork the repository,
-start working from the `develop` branch,
+start working from the `dev` branch,
 and when ready, submit a pull request.
-
-!!! note "Todo"
-
-    Update url address if needed when the package is released.
+The contribution guidelines are detailed
+[here](https://github.com/BecksLab/EcologicalNetworksDynamics.jl/blob/dev/CONTRIBUTING.md).
 
 ## Citing
 
-Please mention EcologicalNetworkDynamics.jl
+Please mention EcologicalNetworksDynamics
 if you use it in research, teaching, or other activities.

docs/src/man/foodwebs.md

@@ -126,7 +126,7 @@ You can pass any of those models, with the required arguments, to generate food
 using EcologicalNetworks
 S = 20 # species richness
 C = 0.2 # connectance
-foodweb = FoodWeb(nichemodel, S; C = C)
+foodweb = FoodWeb(nichemodel, S; C, tol_C = 0.01)
 ```
 
 Moreover, the `method` field has automatically stored

docs/src/man/quickstart.md

@@ -0,0 +1,39 @@
+# Quick start
+
+If it's your first time using EcologicalNetworksDynamics,
+exploring this example might be useful to you
+so that you understand how the package works.
+Try pasting the following code blocks in a Julia REPL.
+
+The first step is to create the structure of the trophic interactions.
+
+```@example quickstart
+using EcologicalNetworksDynamics, Plots
+fw = FoodWeb([1 => 2, 2 => 3]) # 1 eats 2, and 2 eats 3
+```
+
+Then, you can generate the parameter of the model (mostly species traits) with:
+
+```@example quickstart
+p = ModelParameters(fw)
+```
+
+For instance, we can access the species metabolic rate (``x``).
+
+```@example quickstart
+p.biorates.x
+```
+
+At this step we are ready to run simulations,
+we just need to provide initial conditions for species biomasses.
+
+```@example quickstart
+B0 = [1, 1, 1] # the 3 species start with a biomass of 1
+out = simulate(p, B0)
+```
+
+Lastly, we can plot the biomass trajectories.
+
+```@example quickstart
+plot(out)
+```

src/EcologicalNetworksDynamics.jl

@@ -1,3 +1,27 @@
+"""
+EcologicalNetworksDynamics
+
+Provide tools to simulate biomass dynamics in trophic and multiplex networks.
+Trophic networks only include feeding interactions,
+while multiplex networks also include non-trophic interactions such as
+interference between predators, or plant facilitation.
+The basic workflow has been designed to be as simple as possible,
+while remaining flexible for the experienced or adventurous user
+who would like to refine the model and its parameters.
+
+Example of a simple workflow:
+
+```julia
+trophic_backbone = FoodWeb([1 => [2, 3]]) # species 1 eats plants 2 and 3
+multi_net = MultiplexNetwork(trophic_backbone; L_facilitation = 1) # add 1 facilitation link
+p = ModelParameters(multi_net) # generate model parameters
+sol = simulate(p, rand(3)) # run simulation with random initial conditions
+```
+
+For more information, either go through the online documentation at (https://doc-url)
+or if you are looking for the help of a specific function read its docstring
+by writing `?<function_name>` in a Julia REPL.
+"""
 module EcologicalNetworksDynamics
 
 # Dependencies