Split chic integration into subsection and add variable descriptions.

Author: olihen

doc/sphinx/api_manual/API_FFI/Fortran_interface/CHIC_integration.md

@@ -0,0 +1,27 @@
+(part:API_manual:chap:API_FFI:sec:Fortran_interface:subsec:CHIC_integration)=
+
+CHIC Integration
+=================
+
+To illustrate how the World Builder interface can be used, the following section outlines what is done in CHIC:
+
+1. **Initialize the World Builder**:
+    ```fortran
+    call create_world(cworld, 'path/to/world_file.wb', .false., '', 12345)
+    ```
+    - the path to the `.wb` file has to be passed as an input to CHIC
+
+2. **Query Temperature and Composition**:
+    - pass domain boundaries as input to CHIC (analogous to the `.grid` files used for the gwb-grid app {ref}`part:user_manual:chap:how_to_use_the_apps:sec:gwb-grid_app`)
+    - parse grid in given boundaries
+    - overwrite values of temperature and composition at each position:
+    ```fortran
+    ! Query temperature at the given position
+    call temperature_3d(cworld, x, y, z, depth, temperature)
+    ! Query composition at the given position
+    call composition_3d(cworld, x, y, z, depth, composition_number, composition)
+    ```
+3. **Release the World Builder**:
+    ```fortran
+    call release_world(cworld)
+    ```

doc/sphinx/api_manual/API_FFI/Fortran_interface.md renamed to doc/sphinx/api_manual/API_FFI/Fortran_interface/index.md

@@ -1,10 +1,7 @@
-(part:API_manual:chap:API_FFI:sec:Fortran_interface)=
+(part:API_manual:chap:API_FFI:sec:Fortran_interface:subsec:Fortran_integration)=
 FORTRAN interface
 ===========
 
-Explanation of wrapper subroutines
------------
-
 The interface functions are defined in the Fortran wrapper module (`source/world_builder/wrapper_fortran.f90`). Here we provide short explanations for each function (subroutines in Fortran).
 
 ```{important}
@@ -13,14 +10,15 @@ To start the World Builder and create a world from a given `.wb` file, the `crea
 
 ```{code}
 subroutine create_world(cworld, file_name, has_output_dir, output_dir, random_number_seed)
+
 Interface with the World Builder to create a world with a given `.wb` file
 
-PARAMETERS
-    cworld (C_PTR) - variable that points to the world pointer of the world builder
-    file_name (string) - name of the `.wb` file to be used
-    has_output_dir
-    output_dir
-    random_number_seed (long) - random seed used in creating the world 
+Parameters:
+    cworld (C_PTR) - Variable that points to the world pointer of the world builder
+    file_name (C_CHAR) - Name of the `.wb` file to be used
+    has_output_dir (C_BOOL) - If true, the World Builder gains permission to write files into the given directory (`output_dir`). Currently, these are the World Builder json schema and declarations file.
+    output_dir (C_CHAR) - Path to directory where the files should be written into.
+    random_number_seed (C_LONG) - Random seed used in creating the world 
 ```
 
 After calling `create_world`, the world builder can be queried to output temperature and composition values at a given position. The subroutines for temperature and composition, each have a 2D and 3D variant. Each subroutine creates an interface with a c function of the world builder of the same name.
@@ -51,34 +49,12 @@ Output:
 
 - value (of temperature or composition) at the position specified with x, (y,) z, depth
 
-Example (CHIC)
------------
-
-To illustrate how the World Builder interface can be used, the following section outlines what is done in CHIC:
-
-1. **Initialize the World Builder**:
-    ```fortran
-    call create_world(cworld, 'path/to/world_file.wb', .false., '', 12345)
-    ```
-    - the path to the `.wb` file has to be passed as an input to CHIC
-
-2. **Query Temperature and Composition**:
-    - pass domain boundaries as input to CHIC (analogous to the `.grid` files used for the gwb-grid app {ref}`part:user_manual:chap:how_to_use_the_apps:sec:gwb-grid_app`)
-    - parse grid in given boundaries
-    - overwrite values of temperature and composition at each position:
-    ```fortran
-    ! Query temperature at the given position
-    call temperature_3d(cworld, x, y, z, depth, temperature)
-    ! Query composition at the given position
-    call composition_3d(cworld, x, y, z, depth, composition_number, composition)
-    ```
-3. **Release the World Builder**:
-    ```fortran
-    call release_world(cworld)
-    ```
-
 ```{important}
-The `release_world` subroutine has to be called afterwards, in order to clean up the memory used by the World Builder.
+When done with the World Builder, the `release_world` subroutine has to be called to clean up the memory used by the World Builder.
+```
+
+```{hint}
+A short explanation of how the World Builder is integrated into the Mantle Convection code CHIC can be found on the next page {ref}`part:API_manual:chap:API_FFI:sec:Fortran_interface:subsec:CHIC_integration`
 ```
 
 <!-- With the sphinx Fortran extension, the following syntax would be possible