Create new style documentation alongside syntax documentation

.github/workflows/ci.yml

@@ -34,6 +34,10 @@ jobs:
       - name: Docs
         shell: bash
         run: |
+          # Ensure no stubs are generated these should be already completed by the developer
+          apptainer exec hippo-release.sif bash -c "cd /opt/hippo/doc && [ \$(./moosedocs.py generate hippoApp | wc -l) -eq 1 ]"
+
+          # Build the docs
           apptainer exec hippo-release.sif bash -c "cd /opt/hippo/doc && ./moosedocs.py build --destination=${{ github.workspace }}/doc/htmldoc"
           [ -f ${{ github.workspace }}/doc/htmldoc/index.html ]
       - name: Artifact docs

doc/config.yml

@@ -1,23 +1,34 @@
 Content:
-    hippo:
-        root_dir: ${ROOT_DIR}/doc/content
-    moose:
-        root_dir: ${MOOSE_DIR}/framework/doc/content
-        content:
-            - js/*
-            - css/*
-            - contrib/**
-            - media/**
+  hippo:
+    root_dir: ${ROOT_DIR}/doc/content
+  moose:
+    root_dir: ${MOOSE_DIR}/framework/doc/content
+    content:
+      - js/*
+      - css/*
+      - contrib/**
+      - media/**
 
 Renderer:
-    type: MooseDocs.base.MaterializeRenderer
+  type: MooseDocs.base.MaterializeRenderer
 
 Extensions:
-    MooseDocs.extensions.navigation:
-        name: hippo
-        repo: https://github.com/aurora-multiphysics/hippo/
-    MooseDocs.extensions.appsyntax:
-        executable: ${ROOT_DIR}
-        remove: !include ${MOOSE_DIR}/framework/doc/remove.yml
-        includes:
-            - include
+  MooseDocs.extensions.navigation:
+    name: hippo
+    repo: https://github.com/aurora-multiphysics/hippo/
+    menu:
+      Getting started:
+        Installation: installation.md
+        Apptainer: apptainer.md
+      Documentation:
+        Input syntax: /source/index.md
+        Examples: /examples/index.md
+        Development guide: developer_guide.md
+      Case studies:
+        Case studies: case_studies.md
+  MooseDocs.extensions.appsyntax:
+    executable: ${ROOT_DIR}
+    remove:
+      framework: !include ${MOOSE_DIR}/framework/doc/remove.yml
+    includes:
+      - include

doc/content/apptainer.md

@@ -0,0 +1,54 @@
+# Apptainer
+
+We make use of [Apptainer](https://apptainer.org/docs/user/main/) containers to test Hippo within the CI pipeline and in the future, we intend to include them as part of Hippo releases.
+There are two containers
+- **Development container:** this contains all of Hippo's dependencies but not Hippo itself.
+The definition file can be found [here](https://github.com/aurora-multiphysics/hippo/apptainer/hippo-dev.def).
+Stored under
+[UKAEA's Quay.io organisation](https://quay.io/repository/ukaea/hippo)
+with name `hippo:dev-` followed by the first 10 characters of the Git revision that created it.
+- **Release container:** used to build and test Hippo within the CI environment.
+The definition file can be found [here](https://github.com/aurora-multiphysics/hippo/apptainer/hippo-release.def).
+
+
+## Building the containers
+
+To build the release container locally, run (from the root directory)
+
+```bash
+apptainer build hippo-release.sif apptainer/hippo-release.def
+```
+
+## Running the containers
+
+The most common way to use MPI with Apptainer,
+is to use the [hybrid approach](https://apptainer.org/docs/user/latest/mpi.html),
+in which the host MPI is used to launch the container and works with the MPI installed in the container.
+This means that the MPI in the container must be compatible with the host MPI.
+The release container currently uses OpenMPI, but in the future we plan to alsp support MPICH.
+
+To run Hippo using the container with MPI on 4 processes
+
+```bash
+mpirun -n 4 apptainer run ./hippo-release.sif -i main.i
+```
+
+or more simply
+
+```bash
+mpirun -n 4 ./hippo-release.sif -i main.i
+```
+
+## The CI pipeline
+
+The development container is created on
+[workflow dispatch](https://github.com/aurora-multiphysics/hippo/actions/workflows/deploy-apptainer-dev.yaml)
+and stored under
+[UKAEA's Quay.io organisation](https://quay.io/repository/ukaea/hippo)
+with name `hippo:dev-` followed by the first 10 characters of the Git revision that created it.
+Once the image has been built and pushed to Quay.io,
+a developer should open a PR that updates `.github/workflows/ci.yml`
+A [robot account](https://docs.quay.io/glossary/robot-accounts.html)
+has been set up with write permissions for the Hippo repository.
+This robot account is used to authenticate between Quay and GitHub.
+Contact UKAEA's Quay.io admins (or the RSE team) for support with this account.

doc/content/case_studies.md

@@ -0,0 +1 @@
+# Case studies

doc/content/examples/index.md

@@ -0,0 +1,8 @@
+# Examples
+
+## Conjugate heat transfer
+
+We currently have two examples for the conjugate heat transfer
+
+1. [Flow over heated plate:](examples/step_by_step.md) a simple CHT case highlighting the basic syntax.
+2. [Shell and tube heat exchanger:](examples/shell_tube_hx.md) a more  complex CHT with two fluid domains.

doc/content/step_by_step.md → doc/content/examples/step_by_step.md

@@ -138,7 +138,7 @@ Hippo also implements the `FoamBC` system that allows you to impose boundary con
 on OpenFOAM from the Hippo input file. In this case, we wish to impose a heat flux BC
 on the temperature field. This requires the `FoamFixedGradientBC`, which mirrors OpenFOAM's
 `fixedGradient` BC type. As in this case, we provide a heat flux, we must also provide the
-thermal conductivity, which is specified as the `diffusivity_coefficient`.
+thermal conductivity, which is specified as the `diffusivity`.
 `kappa` is the name of the thermal conductivity variable in OpenFOAM.
 
 ```toml
@@ -148,7 +148,7 @@ thermal conductivity, which is specified as the `diffusivity_coefficient`.
     [solid_heat_flux]
         type = FoamFixedGradientBC
         foam_variable = T
-        diffusivity_coefficient = kappa
+        diffusivity = kappa
     []
 []
 ```

doc/content/hit/step_by_step/fluid.i

@@ -16,7 +16,7 @@
     [solid_heat_flux]
         type = FoamFixedGradientBC
         foam_variable = 'T'
-        diffusivity_coefficient = kappa
+        diffusivity = kappa
         initial_condition = 0
     []
 []

doc/content/index.md

@@ -1,35 +1,30 @@
 !config navigation breadcrumbs=False scrollspy=False
 
-# Hippo
+# Hippo class=center style=font-weight:200;font-size:400%
 
-A MOOSE multiapp wrapping OpenFOAM for conjugate heat transfer problems.
 
-## Installation
+!style halign=center fontsize=120% A MOOSE application wrapping OpenFOAM for multiphysics problems.
 
-Build instructions can be found in the repository's
-[README](https://github.com/aurora-multiphysics/hippo/blob/main/README.md).
+!col! small=12 medium=4 large=4 icon=flash_on
 
-Alternatively, you can use Hippo in a Docker container.
-An image with all of Hippo's dependencies pre-installed
-can be found on [quay.io](https://quay.io/repository/ukaea/hippo).
-You will need to mount and install Hippo within the container.
+### Flexible Multiphysics class=center style=font-weight:200
 
-```shell
-$ git clone https://github.com/aurora-multiphysics/hippo.git
-$ docker run -it -v $(pwd)/hippo:/opt/hippo quay.io/ukaea/hippo:latest bash
-$ make -j
-$ hippo-opt --help
-```
+!style halign=center
+Leverage two of the most popular multiphysics frameworks in OpenFOAM and MOOSE
+!col-end!
 
-## Examples
+!col! small=12 medium=4 large=4 icon=settings
 
-### Conjugate heat transfer
+### Getting started class=center style=font-weight:200
 
-We currently have two examples for the conjugate heat transfer
+!style halign=center
+[Installation](installation.md) and [examples](examples/index.md) can be found here.
+!col-end!
 
-1. [Flow over heated plate:](step_by_step.md) a simple CHT case highlighting the basic syntax.
-2. [Shell and tube heat exchanger:](shell_tube_hx.md) a more  complex CHT with two fluid domains.
+!col! small=12 medium=4 large=4 icon=assessment
 
-## Developer Guide
+### Case studies class=center style=font-weight:200
 
-See [here](developer_guide.md) for developer documentation.
+!style halign=center
+Find relevant an overview of Hippo case studies [here](case_studies.md)
+!col-end!

doc/content/installation.md

@@ -0,0 +1,83 @@
+# Installation
+
+Hippo's source code can be cloned from GitHub:
+
+```bash
+git clone https://github.com/aurora-multiphysics/hippo.git
+```
+
+## Dependencies
+
+First, install the build dependencies
+
+```bash
+apt install \
+    bison \
+    flex \
+    libptscotch-dev \
+    libqt5opengl5-dev \
+    libqt5x11extras5-dev \
+    libxt-dev \
+    make \
+    paraview \
+    paraview-dev \
+    qtbase5-dev \
+    qttools5-dev \
+    qttools5-dev-tools
+```
+
+## Installing OpenFOAM
+
+Hippo currently works with openfoam.org (The OpenFOAM Foundation's)
+flavour of OpenFOAM and has been tested on OpenFOAM-12 specifically.
+Unfortunately, for Hippo to work correctly, OpenFOAM needs to be patched.
+For convenience, the script [`scripts/install-openfoam.sh`](https://github.com/aurora-multiphysics/hippo/blob/main/scripts/install-openfoam.sh)
+has been provided to patch and install OpenFOAM-12.
+To execute the script, run
+
+```bash
+bash ./scripts/install-openfoam.sh
+```
+
+The `-h` flag shows the installation options.
+To set the OpenFOAM build options (e.g., Opt or Debug mode),
+copy `scripts/openfoam-prefs.sh` to `~/.OpenFOAM/prefs.sh`,
+and update the environment variables within.
+The variables will be loaded when `<path/to/OpenFOAM>/etc/bashrc` is sourced
+(which is done automatically by the install script).
+
+## Installing MOOSE
+
+Follow instructions
+[here](https://mooseframework.inl.gov/getting_started/installation/gcc_install_moose.html)
+to build MOOSE.
+
+Hippo requires MOOSE release `2024-09-05-release` or higher.
+
+## Environment
+
+Set (recommend [direnv](https://direnv.net/) for this)
+
+```bash
+MOOSE_DIR=/path/to/moose/dir
+MPI_ROOT=/path/to/mpich/root
+MPI_ARCH_INC="-I/path/to/mpi/includes"
+MPI_ARCH_LIBS="-L/path/to/mpi/libs -lmpi"
+source /path/to/OpenFOAM/etc/bashrc
+```
+
+## Building Hippo
+
+Once the dependencies are built, then (in theory) you should be able to `make` in the root directory:
+
+```bash
+make
+```
+
+Or, for a debug build:
+
+```bash
+METHOD=dbg make
+```
+
+The `-j N` option can be used for multi-threaded builds with `N` threads.

doc/content/source/actions/AddFoamBCAction.md

@@ -0,0 +1,9 @@
+# AddFoamBCAction
+
+!syntax description /FoamBCs/AddFoamBCAction
+
+Provides the `[FoamBCs]` block. More information can be found in the [FoamBCs system documentation](syntax/FoamBCs/index.md).
+
+!syntax description /FoamBCs/AddFoamBCAction
+
+!syntax parameters /FoamBCs/AddFoamBCAction

doc/content/source/actions/AddFoamVariableAction.md

@@ -0,0 +1,13 @@
+# AddFoamVariableAction
+
+!syntax description /FoamVariables/AddFoamVariableAction
+
+Provides the `[FoamVariables]` block. More information can be found in the [FoamVariables system documentation](syntax/FoamBCs/index.md).
+
+## Example Input File Syntax
+
+!! Describe and include an example of how to use the AddFoamVariableAction action.
+
+!syntax description /FoamVariables/AddFoamVariableAction
+
+!syntax parameters /FoamVariables/AddFoamVariableAction

doc/content/source/auxkernels/HeatFluxAux.md

@@ -0,0 +1,17 @@
+# HeatFluxAux
+
+!syntax description /AuxKernels/HeatFluxAux
+
+## Overview
+
+!! Replace these lines with information regarding the HeatFluxAux object.
+
+## Example Input File Syntax
+
+!! Describe and include an example of how to use the HeatFluxAux object.
+
+!syntax parameters /AuxKernels/HeatFluxAux
+
+!syntax inputs /AuxKernels/HeatFluxAux
+
+!syntax children /AuxKernels/HeatFluxAux

doc/content/source/bcs/FoamFixedGradientBC.md

@@ -0,0 +1,47 @@
+# FoamFixedGradientBC
+
+!syntax description /FoamBCs/FoamFixedGradientBC
+
+Imposes Neumann or Flux boundary conditions on OpenFOAM fields using MOOSE input file syntax. Under-the-hood, a auxilliary variable is created in the mirror mesh and the value of this variable
+(whether specified through a transfer of AuxKernel)
+is imposed as a fixedGradient boundary patch.
+If `diffusivity` is specified, the MOOSE variable is imposed a flux,
+otherwise as a simple Neumann boundary condition.
+
+## Example Input File Syntax
+
+In the case that `diffusivity` is not specified
+
+```
+[FoamBCs]
+    [neumann]
+        type = FoamFixedGradientBC
+        foam_variable = T
+        boundary = wall
+    []
+    ...
+[]
+```
+
+If the diffusivity is specified and we wish to apply a heat flux boundary conditions such as in conjugate heat transfer, we use
+
+```
+[FoamBCs]
+    [heat_flux]
+        type = FoamFixedGradientBC
+        foam_variable = T
+        boundary = wall
+        diffusivity = kappa
+    []
+    ...
+[]
+```
+
+where `kappa` is the fluid thermal conductivity in OpenFOAM.
+
+
+!syntax parameters /FoamBCs/FoamFixedGradientBC
+
+!syntax inputs /FoamBCs/FoamFixedGradientBC
+
+!syntax children /FoamBCs/FoamFixedGradientBC