From 4af05f8eb2fcfa2e59b2b699b8c23a89a108da91 Mon Sep 17 00:00:00 2001
From: JordiManyer <jordi.manyer@monash.edu>
Date: Wed, 11 Dec 2024 20:41:46 +1100
Subject: [PATCH] More documentation

---
 docs/src/BlockSolvers.md                 |  8 +++----
 docs/src/index.md                        | 29 ++++++++++++++++++++++++
 src/BlockSolvers/StaggeredFEOperators.jl | 26 +++++++++++++++++++++
 3 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/docs/src/BlockSolvers.md b/docs/src/BlockSolvers.md
index ed746f20..bd3598e8 100644
--- a/docs/src/BlockSolvers.md
+++ b/docs/src/BlockSolvers.md
@@ -60,12 +60,12 @@ BlockTriangularSolver(blocks::AbstractMatrix{<:SolverBlock},solvers ::AbstractVe
 BlockTriangularSolver(solvers::AbstractVector{<:LinearSolver})
 ```
 
-## Staggered FE Operators
+## Staggered FEOperators
 
 ```@docs
 StaggeredFESolver
 StaggeredFEOperator
-AffineStaggeredFESolver
-NonlinearStaggeredFESolver
-solve!(xh, solver::StaggeredFESolver{NB}, op::StaggeredFEOperator{NB}, ::Nothing)
+StaggeredAffineFEOperator
+StaggeredNonlinearFEOperator
+solve!(xh, solver::StaggeredFESolver{NB}, op::StaggeredFEOperator{NB}, ::Nothing) where {NB}
 ```
diff --git a/docs/src/index.md b/docs/src/index.md
index d80b3d16..d79076ed 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -10,6 +10,8 @@ GridapSolvers provides algebraic and non-algebraic solvers for the Gridap ecosys
 
 Solvers follow a modular design, where most blocks can be combined to produce PDE-taylored solvers for a wide range of problems.
 
+## Table of contents
+
 ```@contents
 Pages = [
   "SolverInterfaces.md",
@@ -20,3 +22,30 @@ Pages = [
   "PatchBasedSmoothers.md"
   ]
 ```
+
+## Documentation and examples
+
+A (hopefully) comprehensive documentation is available [here](https://gridap.github.io/GridapSolvers.jl/stable/).
+
+A list of examples is available in the documentation. These include some very well known examples such as the Stokes, Incompressible Navier-Stokes and Darcy problems. The featured scripts are available in `test/Applications`.
+
+An example on how to use the library within an HPC cluster is available in `joss_paper/scalability`. The included example and drivers are used to generate the scalability results in our [JOSS paper](https://doi.org/10.21105/joss.07162).
+
+## Installation
+
+GridapSolvers is a registered package in the official [Julia package registry](https://github.com/JuliaRegistries/General).  Thus, the installation of GridapSolvers is straight forward using the [Julia's package manager](https://julialang.github.io/Pkg.jl/v1/). Open the Julia REPL, type `]` to enter package mode, and install as follows
+
+```julia
+pkg> add GridapSolvers
+pkg> build
+```
+
+Building is required to link the external artifacts (e.g., PETSc, p4est) to the Julia environment. Restarting Julia is required after building in order to make the changes take effect.
+
+### Using custom binaries
+
+The previous installations steps will setup GridapSolvers to work using Julia's pre-compiled artifacts for MPI, PETSc and p4est. However, you can also link local copies of these libraries. This might be very desirable in clusters, where hardware-specific libraries might be faster/more stable than the ones provided by Julia. To do so, follow the next steps:
+
+- [MPI.jl](https://juliaparallel.org/MPI.jl/stable/configuration/)
+- [GridapPETSc.jl](https://github.com/gridap/GridapPETSc.jl)
+- [GridapP4est.jl](https://github.com/gridap/GridapP4est.jl), and [P4est_wrapper.jl](https://github.com/gridap/p4est_wrapper.jl)
diff --git a/src/BlockSolvers/StaggeredFEOperators.jl b/src/BlockSolvers/StaggeredFEOperators.jl
index 53558ff3..2d3158e7 100644
--- a/src/BlockSolvers/StaggeredFEOperators.jl
+++ b/src/BlockSolvers/StaggeredFEOperators.jl
@@ -142,6 +142,19 @@ struct StaggeredAffineFEOperator{NB,SB} <: StaggeredFEOperator{NB,SB}
   end
 end
 
+"""
+    function StaggeredAffineFEOperator(
+      biforms::Vector{<:Function},
+      liforms::Vector{<:Function},
+      trials::Vector{<:FESpace},
+      tests::Vector{<:FESpace},
+      [assems::Vector{<:Assembler}]
+    )
+
+Constructor for a `StaggeredAffineFEOperator` operator, taking in each 
+equation as a pair of bilinear/linear forms and the corresponding trial/test spaces.
+The trial/test spaces can be single or multi-field spaces.
+"""
 function StaggeredAffineFEOperator(
   biforms::Vector{<:Function},
   liforms::Vector{<:Function},
@@ -233,6 +246,19 @@ struct StaggeredNonlinearFEOperator{NB,SB} <: StaggeredFEOperator{NB,SB}
 end
 
 # TODO: Can be compute jacobians from residuals? 
+
+"""
+    function StaggeredNonlinearFEOperator(
+      res::Vector{<:Function},
+      jac::Vector{<:Function},
+      trials::Vector{<:FESpace},
+      tests::Vector{<:FESpace}
+    )
+
+Constructor for a `StaggeredNonlinearFEOperator` operator, taking in each 
+equation as a pair of residual/jacobian forms and the corresponding trial/test spaces.
+The trial/test spaces can be single or multi-field spaces.
+"""
 function StaggeredNonlinearFEOperator(
   res::Vector{<:Function},
   jac::Vector{<:Function},