docu: restructering of documentation

doc/src/components.dox

@@ -2,37 +2,10 @@
 #
 # SPDX-License-Identifier: CC-BY-4.0
 
-/**
- * \page yac_libs YAC libaries
-
-Information on how to configure, build, install, and link YAC can be found
-\subpage installing_yac "here".
-
-YAC contains three libraries.
-
-\section yac_libs_core YAC Core libary
-
-\include{doc,prefix=yac_libs} doc/src/lib_core.dox
-
-\section yac_libs_mci YAC MCI library
-
-\include{doc,prefix=yac_libs} doc/src/lib_mci.dox
-
-\section yac_libs_utils YAC Utility libary
-
-\include{doc,prefix=yac_libs} doc/src/lib_utils.dox
-
-<hr>
-
-\subpage yac_lib_core "Core"
-\subpage yac_lib_mci "MCI"
-\subpage yac_lib_utils "Utilities"
- */
-
 /**
  * \page yac_lib_core YAC Core library
 
-\include{doc} doc/src/lib_core.dox
+\include{doc,prefix=yac_lib_core_} doc/src/lib_core.dox
 
 <hr>
 
@@ -46,28 +19,58 @@ YAC contains three libraries.
 /**
  * \page yac_lib_mci YAC MCI library
 
-\include{doc} doc/src/lib_mci.dox
+\include{doc,prefix=yac_lib_mci_} doc/src/lib_mci.dox
 
 <hr>
 
-\subpage usage
-\subpage overview
-\subpage yaml_file
-\subpage page_raw_exchange
-\subpage init_yac_detail
-\subpage yinstance
+\subpage overview "Overivew"
+\subpage usage "User Guide"
+\subpage reference "Reference"
+\subpage pythonbindings "Python bindings"
+\subpage yaml_file "Configuration Files"
+\subpage page_raw_exchange "Raw data exchange"
+\subpage init_yac_detail "Initialisation"
+\subpage yinstance "Instance"
 
 */
 
 /**
  * \page yac_lib_utils YAC Utility libary
 
-\include{doc} doc/src/lib_utils.dox
+\include{doc,prefix=yac_lib_utils_} doc/src/lib_utils.dox
 
 <hr>
 
 */
 
+/**
+ * \page yac_libs YAC libaries
+
+Information on how to configure, build, install, and link YAC can be found
+\subpage installing_yac "here".
+
+YAC contains three libraries.
+
+\section yac_libs_core YAC Core libary
+
+\include{doc,raise=1,prefix=yac_libs_core_} doc/src/lib_core.dox
+
+\section yac_libs_mci YAC MCI library
+
+\include{doc,raise=1,prefix=yac_libs_mci_} doc/src/lib_mci.dox
+
+\section yac_libs_utils YAC Utility libary
+
+\include{doc,raise=1,prefix=yac_libs_utils_} doc/src/lib_utils.dox
+
+<hr>
+
+\subpage yac_lib_core "Core"
+\subpage yac_lib_mci "MCI"
+\subpage yac_lib_utils "Utilities"
+
+ */
+
 /**
  * \page yac_tools YAC tools
 

doc/src/lib_core.dox

 The \ref yac_lib_core "YAC Core library" contains all functionallity required
 for generating weights and doing basic exchanges using them.
 
-It has a low-level C and Fortran interface.
+It has a low-level C and \ref yac_core.F90 "Fortran" interface. The C header
+file (yac_core.h) is generated automatically during the building process.
 
-Additional information:
- - \ref interp_main "Interpolation"
- - \ref io_config_detail
- - \ref clipping
- - \ref sphere_part_docu
+\section add_info Additional information
+
+\subsection interpolation Interpolation
+
+YAC provides extensive interpolation capabilities. A description can be found
+\ref interp_main "here".
+
+\subsection io_config_detail_ Configuration of parallel IO in YAC
+
+YAC access weight and grid files in parallel. The user can provide hints to
+YAC in form of \ref io_config_detail "multiple environment variables", which
+are evalutated during runtime.
+
+\subsection io_clipping Polygon clipping in YAC
+
+Some information on the implementation of polygon clipping algorithm in YAC
+can be found \ref clipping "here".
+
+\subsection sphere_part_docu_ Sphere Partitioning Algorithm
+
+The Sphere Partitioning Algorithm is use in YAC for efficiently accessing data
+defined on the surface of a sphere. A basic description can be found
+\ref sphere_part_docu "here".

doc/src/lib_mci.dox

-The \ref yac_lib_mci "Model Coupling Interface (MC) library" is a user friendly
-high-level interface for the \ref yac_lib_core and provides additional
-capabilities.
-
-It has a C, Fortran, and Python interface.
-
-Additional information:
- - \ref usage
- - \ref overview
- - \ref yaml_file
- - \ref page_raw_exchange
- - \ref init_yac_detail
- - \ref yinstance
+The \ref yac_lib_mci "Model Coupling Interface (MCI) library" is a library build
+on top of the \ref yac_lib_core "YAC Core library" and provides additional
+capabilities that improve usability for earth system model components.
+
+It has a high-level \ref yac.h "C", \ref yac_module.F90 "Fortran", and
+\ref yac.pyx "Python" interface.
+
+\section interface User interface
+
+- \ref overview "Basic introduction"
+- \ref usage "Detailed user guide"
+- \ref reference "Interface reference"
+- \ref yaml_file "Configuration files"
+
+\section python The Python bindings
+
+Information on how to build and use the Python bindings for the
+YAC MCI libary can be found \ref pythonbindings "here"
+
+\section add_info Additional information
+
+\subsection init_yac_detail_ Initialising YAC in complex setups
+
+I complex earth system model configurations initialisation of MPI can be a
+difficult task, especially if a setup uses more than one coupling libary or
+uses additional IO server components. How to handle these cases with YAC
+is discussed in detail \ref init_yac_detail "here".
+
+\subsection instances_ YAC instances
+
+Within a coupled configuration, YAC supports the usage multiple independent
+YAC instances. This concept and its usage is explained \ref yinstance "here".
+
+\subsection page_raw_exchange_ Raw data exchange
+
+In case target components want to receive unaltered source data and apply
+weights computed by YAC on their own, the
+\ref page_raw_exchange "raw data exchange feature" can be used. This can be
+useful in case functionallity similar to an exchange grid is required or a
+component wants to do stochastic coupling, which is not directly supported by
+YAC.

doc/src/lib_utils.dox

@@ -6,4 +6,5 @@ includes:
 - generation of regular gaussian and cubed sphere grids
 - VTK-file generation
 
-It has a C and Fortran interface.
+It has a C and \ref yac_utils.F90 "Fortran" interface. The C header
+file (yac_utils.h) is generated automatically during the building process.

doc/src/overview.dox

@@ -65,8 +65,4 @@ C (prefix <em>yac_c</em>) are available. The Fortran interface is provided using
 the ISO-C standard. The python bindings need to be enabled explicitly by passing
 `--enable-python-bindings` to `./configure`</p>
 
-A detailed description of the Fortran, Python and C interfaces can be found
-\subpage reference "here".
-The python bindings are documented \subpage pythonbindings "here".
-
 */