Merge branch '77-define-the-public-api' into 'master'

Resolve "Define the public API"

Closes #77

See merge request !69

CHANGELOG.md

@@ -11,6 +11,7 @@
 * CI pipeline now also compiles a Debug build with the LLVM Clang compiler
 * Add `.gitattributes` for `CHANGELOG.md` to reduce merge conflicts with
     `merge=union`
+* Public API definition in documentation.
 
 ### Changed
 * Update code base to DUNE v2.6
@@ -30,6 +31,9 @@
     explicitly in the config file. The key will become mandatory in future
     versions.
 
+### Removed
+* Complete doxygen documentation from Sphinx docs.
+
 ### Fixed
 * The source code is now compatible to the Clang LLVM compiler.
     DORiE can now be compiled with the onboard compiler on macOS.

doc/CMakeLists.txt

@@ -33,10 +33,9 @@ dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
 	RST_SOURCES
 		index.rst
 		doxygen-guide.rst
-		doxygen-modules.rst
-		doxygen-quick-all.rst
 		logs-install.rst
 		other-cmake.rst
+		public-api.rst
 		python-dorie-wrapper.rst
 		python-dorie-parscraper.rst
 		python-dorie-testtools.rst
@@ -45,6 +44,7 @@ dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
 		quickstart-cookbook.rst
 		quickstart-installation.rst
 		quickstart-parameters.rst
+		quickstart-parameter-file.rst
 	MODULE_ONLY)
 
 if(TARGET sphinx_html)

doc/conf.py.in

@@ -85,17 +85,18 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'DORiE'
-copyright = '2016, DORiE developer team'
+copyright = '2018, DORiE developer team'
 author = 'Dion Häfner'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = '0.9'
-# The full version, including alpha/beta/rc tags.
-release = '0.9-master'
+with open("@PROJECT_SOURCE_DIR@/VERSION") as version_file:
+    # The short X.Y version.
+    version = version_file.read()
+    # The full version, including alpha/beta/rc tags.
+    release = version_file.read()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/doxygen-guide.rst

@@ -46,17 +46,13 @@ for computing the solution.
 
 .. doxygenfunction:: build_grid_cube
 
-.. doxygenfunction:: RichardsSolverSimplex
-
-.. doxygenfunction:: RichardsSolverRectangular
-
 .. _code-solver:
-Solver Routine
---------------
-The Solver Routine receives the assembled Grid Function Space and initializes the PDELab Backends
+Simulation
+----------
+The Simulation template receives the assembled Grid Function Space and initializes the PDELab Backends
 to compute the solution.
 
-.. doxygenfunction:: RichardsSolver
+.. doxygenclass:: Dune::Dorie::Simulation
 
 .. _code-param:
 Richards Equation Classes
@@ -66,7 +62,10 @@ have to be represented. This is achieved by building objects which provide appro
 Boundary Conditions, Parameters and Sink/Source terms, depending on both time and space. There are
 three classes with standardized function queries for these tasks:
 
-.. doxygenclass:: Dune::Dorie::RichardsEquationParameter
+.. doxygenclass:: Dune::Dorie::ParameterizationBase
+   :members:
+
+.. doxygenclass:: Dune::Dorie::MualemVanGenuchten
    :members:
 
 .. doxygenclass:: Dune::Dorie::FlowBoundary
@@ -82,10 +81,10 @@ The local operators bind to the PDELab backend and compute the local residual al
 They represent the numeric implementation of the PDE's *strong formulation*.
 DORiE uses the mass conserving Discontinuous Galerkin (DG) discretization scheme.
 
-.. doxygenclass:: Dune::Dorie::RichardsDGSpatialOperator
+.. doxygenclass:: Dune::Dorie::Operator::RichardsDGSpatialOperator
    :members:
 
-.. doxygenclass:: Dune::Dorie::RichardsDGTemporalOperator
+.. doxygenclass:: Dune::Dorie::Operator::RichardsDGTemporalOperator
    :members:
 
 .. _code-controller:
@@ -106,8 +105,8 @@ local residuals along the grid. The residual represents the estimated error of t
 on an estimation on the error in the water flux along an grid interface. Depending on the refinement
 scheme, the grid is then refined or coarsened at positions of large or small errors, respectively.
 
-.. doxygenclass:: Dune::Dorie::FluxErrorEstimator
+.. doxygenclass:: Dune::Dorie::Operator::FluxErrorEstimator
    :members:
 
-.. doxygenclass:: Dune::Dorie::AdaptivityController
+.. doxygenclass:: Dune::Dorie::AdaptivityHandler
    :members:

doc/doxygen-modules.rst

-******************
-DORiE Code Modules
-******************
\ No newline at end of file

doc/doxygen-quick-all.rst

-***********************
-Complete Class Overview
-***********************
-
-.. doxygenfile:: dorie.cc
-
-.. doxygenfunction:: RichardsSolverSimplex
-
-.. doxygenfunction:: RichardsSolverRectangular
-
-.. doxygenfunction:: RichardsSolver
-
-.. doxygennamespace:: Dune::Dorie
-	:members:
-	:private-members:
-	:protected-members:
-	:undoc-members:

doc/index.rst

@@ -14,6 +14,11 @@ Introduction
 =============
 Welcome to the DORiE Documentation!
 
+DORiE is a DUNE module for solving the Richards equation. The source code is
+available from the `public repository <https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie>`_.
+A ready-to-use application is available from `Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_.
+DORiE is licensed under the `MIT License <https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/blob/master/LICENSE.md>`_.
+
 Never used DORiE before? Get to learn its features by working through :ref:`quickstart`.
 If you have already installed DORiE, jump straight to the :doc:`quickstart-cookbook`
 and have a look at the test cases described therein!
@@ -26,6 +31,9 @@ A complete documentation of the :ref:`DORiE source code <c-reference>`, the
 :ref:`Python modules <python-reference>` and the :ref:`CMake files <cmake-reference>`
 is provided for DORiE developers.
 
+DORiE complies to `Semantic Versioning <https://semver.org/>`_. Version number
+assignment and increment are based on the :doc:`public-api`.
+
 Contents
 =========
 
@@ -41,6 +49,8 @@ Quick Start
    quickstart-cookbook
    quickstart-parameters
    quickstart-bcfile
+   python-dorie-wrapper
+   public-api
 
 .. _c-reference:
 

doc/public-api.rst

+*********************
+Public API Definition
+*********************
+
+DORiE's Public API comprises the usage of the compiled program as well as the
+main code segments for using instances of DORiE in other (DUNE) modules and
+programs.
+
+Command Line API
+================
+
+The compiled program and the Docker application are executed via the
+:doc:`Command Line Interface <python-dorie-wrapper>`. The specifications for the
+respective configuration files are given in the
+:doc:`Config File Guide <quickstart-parameters>`.
+
+The main routine (`dorie run <config>`) also requires input files for
+:doc:`boundary conditions <quickstart-bcfile>` and
+:doc:`soil parameters <quickstart-parameter-file>`.
+
+Code API
+========
+
+DORiE supplies the `Simulation` template. This is the main class for assembling
+and running the solver.
+
+.. doxygenclass:: Dune::Dorie::Simulation
+   :members:
+
+The simulation template requires compile-time type specifications wrapped in a
+suitable `Traits` structure.
+
+.. doxygenstruct:: Dune::Dorie::BaseTraits
+   :members:
+   :undoc-members:

doc/python-dorie-wrapper.rst

-********************
-DORiE Wrapper Script
-********************
+****************************
+DORiE Command Line Interface
+****************************
 
 DORiE consists of two main executables and multiple utility scripts. This wrapper script supplies input files, and manages the execution of these routines. It takes three main arguments:
 

doc/quickstart-parameter-file.rst

+***********************************
+Parameter Field File Specifications
+***********************************
+
+The parameter field file is used to supply soil parameter information to the
+simulation. It is supplied as
+`H5 File <https://support.hdfgroup.org/HDF5/doc/H5.intro.html>`_.
+
+The Parameter Field Generator module always generates files compliant to this
+specification.
+
+The structure of this file is as follows:
+
+* H5Group: `parameters`
+
+    Attributes:
+
+    * array: `extensions` : n-dimensional spatial extensions of the field
+    * bool: `millerSimilarity` : whether Miller scaling shall be used
+    * string: `parameterization` : Only "vanGenuchten" supported
+    * double: `variance` : Variance of the Gaussian random field for Miller scaling
+
+
+    * H5Group: `vanGenuchten`
+
+        Datasets for each parameter in a n-dimensional field. The extensions of
+        all datasets must match. Additionally, there is the `raw_field` dataset,
+        specifying the natural logarithm of the Miller scaling factor.
+
+        * H5Dataset: `alpha`
+        * H5Dataset: `k0`
+        * H5Dataset: `n`
+        * H5Dataset: `tau`
+        * H5Dataset: `theta_r`
+        * H5Dataset: `theta_s`
+        * H5Dataset: `raw_field`
\ No newline at end of file

doc/quickstart-parameters.rst

-DORiE Parameter File Guide
-**************************
+DORiE Configuration File Guide
+******************************
 
 .. contents::
 	:depth: 2
@@ -44,10 +44,23 @@ A set of rules defines this syntax:
 
 .. _inifile-cheatsheet:
 
-Cheat Sheet
-===========
+Cheat Sheets
+============
+
+These cheat sheets are automatically generated by
+:doc:`the Parameter Scraper <python-dorie-parscraper>`.
+The configuration files are used for the Parameter Field Generator module and
+the main simulation routine. They are executed by `dorie pfg <config>` and
+`dorie run <config>`, respectively, see the
+:doc:`CLI documentation <python-dorie-wrapper>`.
+
+Parameter Field Generator
+-------------------------
+
+.. include:: default_files/field-parameters.rst
+
 
-This is a description of all parameters that have to be specified to run DORiE.
-It is automatically generated by :doc:`the Parameter Scraper <python-dorie-parscraper>`.
+Main Routine
+------------
 
 .. include:: default_files/parameters.rst

dune.module

@@ -4,7 +4,7 @@
 
 #Name of the module
 Module: dorie
-Version: 0.9
+Version: 1.1.0-pre
 Maintainer: dorieteam@iup.uni-heidelberg.de
 #depending on
 Depends: dune-pdelab dune-uggrid dune-randomfield