Further restructure docs. Add new doc pages

* Adjust toctree to have proper sections
* Add new doc pages:
  - Feature overview
  - Data I/O
* Add new doc section 'Introduction'
* Rename main file to `index.rst`

README.md

-# DORiE README
+# DORiE
 (**D**UNE-**O**perated **Ri**chards equation solving **E**nvironment)
 
 DORiE is a software suite for solving the Richards Equation. The core feature is a C++ PDE-solver powered by [DUNE](https://dune-project.org/) and the [DUNE-PDELab](https://dune-project.org/modules/dune-pdelab/) module. It implements a Discontinous Galerkin (DG) discretization scheme on structured rectangular / cubic and unstructured simplex grids in two and three spatial dimensions, and makes use of advanced features like adaptive grid refinement.

doc/cookbook/index.rst

-The Cook Book
-*************
-
 Introduction
-============
+************
+
 This part of the documentation guides through increasingly complicated
 use-cases of DORiE. It is intended for users who wish to jump right into using
 DORiE, without much knowledge of all its functions. The relevant manual pages
 will be linked on the way.
 
 Prerequisites
--------------
+=============
+
 You need a working application. You can either use the image shipped via
 `Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_ or use a local
-installation. See the :doc:`installation manual <man-installation>` for
-details. Additionally, install Paraview_ for analyzing the output.
-
-Data I/O
---------
-
-Let's start with the files required for running DORiE and the data that can
-be retrieved!
-
-Input Files
-^^^^^^^^^^^
-Templates for the required files can conveniently be generated with the
-:doc:`CLI </manual/cli>`.
-
-* :doc:`Configuration File </manual/config-file>` (``.ini``):
-  The main input file for the solver. Template: ``config.ini``
-
-* :ref:`Parameterization Data File <man-parameter_file>` (``.yml``):
-  Specifies the soil parameterization type(s) and parameters.
-  Template: ``param.yml``
-
-* :doc:`Boundary Condition Data File </manual/bcfile>` (``.bcdat``):
-  Specifies the boundary segmentation and the boundary conditions.
-  Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``
-
-* :ref:`GMSH Mesh File <man-grid_gmsh>` (optional): Mesh with possibly
-  complicated geometry to build an unstructured grid from.
-
-* :ref:`Grid Mapping H5 File <man-grid_mapping-dataset>` (optional):
-  Used to generate heterogeneous soil architectures and boundary segmentations
-  for rectangular grids.
-
-* :ref:`Scaling Field H5 Files <man-parameter_scaling>` (optional):
-  Datasets for interpolating local heterogeneities in the parameterization.
-
-Output Files
-^^^^^^^^^^^^
-
-* Time Stamp File (``.pvd``): Lists the time step information and the
-  respective VTK output files of a single program run. This file is always
-  saved into the directory from which DORiE was executed.
-
-* VTK Files (``.vtu``): The output data in unstructured grid format.
-  It contains multiple datasets:
-
-  - ``head``: Matric head
-  - ``K0``: Saturated conductivity
-  - ``flux``: Water flux (not reconstructed!)
-  - ``theta_w``: Volumetric water content
-  - ``Theta``: Water saturation
-
-* VTK Parallel Collection Files (``.pvtu``): Merging multiple VTK files in case
-  DORiE is run in parallel.
+installation. See the installation manual for details.
+Additionally, install Paraview_ for analyzing the output.
 
 .. _Paraview: http://www.paraview.org/download/
 .. _Gmsh: http://gmsh.info

doc/contents.rst → doc/index.rst

-The documentation of DORiE
-***************************
+DORiE Documentation
+*******************
 
-.. ifconfig:: deploy_mode
-
-    .. warning::
-
-        This documentation was built automatically for the |branch| branch of the repository
-        at |today|.
-        Please note that it does not necessarily correspond to the version you are using.
-
-
-Introduction
-=============
 Welcome to the DORiE Documentation!
 
 DORiE is a DUNE module for solving the Richards equation. The source code is
@@ -19,32 +8,39 @@ available from the `public repository <https://ts-gitlab.iup.uni-heidelberg.de/d
 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 :doc:`the manual <manual/index>`.
-If you have already installed DORiE, jump straight to the :doc:`Cook Book <cookbook/index>`
-and have a look at the test cases described therein!
-
 DORiE complies to `Semantic Versioning <https://semver.org/>`_. Version number
 assignment and increment are based on the :doc:`public-api`.
 
-Contents
-=========
 
-.. _quickstart:
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
 
-Manual
-------
+   introduction/install-prep
+   The README <introduction/readme>
+   introduction/features
+   introduction/data-io
 
 .. toctree::
-   :maxdepth: 1
-
-   manual/index
+   :maxdepth: 2
+   :caption: Manual
+
+   manual/cli
+   manual/config-file
+   manual/grid
+   manual/parameter-file
+   manual/bcfile
    public-api
-   cookbook/index
-   python/index
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Cook Book
 
-Indices and tables
-==================
+   cookbook/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Python Modules
+   :glob:
 
-* :ref:`genindex`
-* :ref:`modindex`
+   python/*

doc/introduction/data-io.rst

+Data I/O
+********
+
+Executing DORiE requires several input files, some of which are optional and
+depending on the mode the program runs in. The configuration input files can
+typically be created and manipulated by any text editor. For larger portions
+of input data we use HDF5_, a hierachical binary data format. These files can
+easily be written using the h5py_ Python module.
+
+DORiE writes output files in the VTK_ format, a filetype suitable for storing
+grid-based datasets. These files can be evaluated interactively using
+Paraview_. The VTK software library can be included into C++ code and even
+has :ref:`Python bindings <https://pypi.org/project/vtk/>`.
+
+Input Files
+===========
+
+Templates for the required files can conveniently be generated with the
+:doc:`CLI </manual/cli>`.
+
+* :doc:`Configuration File </manual/config-file>` (``.ini``):
+  The main input file for the solver. Template: ``config.ini``
+
+* :ref:`Parameterization Data File <man-parameter_file>` (``.yml``):
+  Specifies the soil parameterization type(s) and parameters.
+  Template: ``param.yml``
+
+* :doc:`Boundary Condition Data File </manual/bcfile>` (``.bcdat``):
+  Specifies the boundary segmentation and the boundary conditions.
+  Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``
+
+* :ref:`GMSH Mesh File <man-grid_gmsh>` (optional): Mesh with possibly
+  complicated geometry to build an unstructured grid from.
+
+* :ref:`Grid Mapping H5 File <man-grid_mapping-dataset>` (optional):
+  Used to generate heterogeneous soil architectures and boundary segmentations
+  for rectangular grids.
+
+* :ref:`Scaling Field H5 Files <man-parameter_scaling>` (optional):
+  Datasets for interpolating local heterogeneities in the parameterization.
+
+Output Files
+============
+
+* Time Stamp File (``.pvd``): Lists the time step information and the
+  respective VTK output files of a single program run. This file is always
+  saved into the directory from which DORiE was executed.
+
+* VTK Files (``.vtu``): The output data in unstructured grid format.
+  It contains multiple datasets:
+
+  - ``head``: Matric head
+  - ``K0``: Saturated conductivity
+  - ``flux``: Water flux (not reconstructed!)
+  - ``theta_w``: Volumetric water content
+  - ``Theta``: Water saturation
+
+* VTK Parallel Collection Files (``.pvtu``): Merging multiple VTK files in case
+  DORiE is run in parallel.
+
+.. _HDF5: https://www.hdfgroup.org/solutions/hdf5/
+.. _h5py: https://www.h5py.org/
+.. _Paraview: https://www.paraview.org/
+.. _VTK: https://vtk.org/

doc/introduction/features.rst

+****************
+Feature Overview
+****************
+
+DORiE is a flexible partial differential equation (PDE) solver based on DUNE_
+and the DUNE-PDELab_ module. DORiE runs in 2D and 3D and computes solutions on
+structured and unstructured grids.
+
+Richards Solver
+===============
+
+The Richards equation describes water flow in unsaturated porous media by two
+state variables, the *matric head* :math:`h_m \, [\mathrm{m}]` and the
+*volumetric water content* :math:`\theta_w`,
+
+.. math::
+
+   \frac{\partial}{\partial t} \theta_w
+     - \nabla \left[ K (\theta_w)
+                     \left[ \nabla h_m - \mathbf{\hat{g}} \right]
+              \right]
+   = 0,
+
+where :math:`K \, [\mathrm{ms}^{-1}]` is the hydraulic conductivity
+and :math:`\mathbf{\hat{g}}` is the unit vector in the direction of
+gravitational force. To solve the equation, we need to convert the matric head
+into water content and vice versa. The function :math:`\theta_w (h_m)` is
+called *retention curve*. Both functions :math:`\theta_w (h_m)` and
+:math:`K (\theta_w)` are supplied by a *parameterization* and represent the
+hydraulic material properties.
+
+DORiE solves the Richards equation for the matric head because it that a
+reformulation of the matric potential :math:`\psi_m [\mathrm{Jm}^{-3}]` which,
+by definition, is continuous and differentiable at any point in the soil.
+Depending on the soil architecture, the hydraulic parameters may be
+discontinuous which would lead to water content and conductivity exhibiting
+singularities.
+
+.. _DUNE: https://www.dune-project.org/
+.. _DUNE-PDELab: https://www.dune-project.org/modules/dune-pdelab/

doc/manual/install-prep.rst → doc/introduction/install-prep.rst

@@ -26,25 +26,6 @@ To install and run DORiE, your computer needs to meet the following requirements
 
 - about 10GB of free disk space
 
-Cloning The Repository
-======================
-
-Create a new folder at a suitable location on your machine. Navigate to it, and
-clone the DORiE repository by executing
-
-.. code-block:: shell
-
-    git clone ssh://git@ts-gitlab.iup.uni-heidelberg.de:10022/dorie/dorie.git
-
-in the terminal. By default, the remote host will be called ``origin``, and the
-``master`` branch will be checked out. If you wish to checkout another branch, do so by calling
-
-.. code-block:: shell
-
-    git checkout --track origin/<branch>
-
-from a terminal inside the repository folder. Refer to the `Atlassian Git Tutorial <https://www.atlassian.com/git>`_ for more information on using Git.
-
 
 OS-Dependent Configuration
 ==========================

doc/manual/cli.rst

@@ -10,7 +10,7 @@ This wrapper script supplies input files, and manages the execution of these
 routines. The CLI is available from within the virtual environment
 (``venv``).
 
-The virtual environment
+The Virtual Environment
 =======================
 
 A `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_ is

doc/manual/index.rst

-The Manual
-==========
-
-This section of the documentation provides detailed information on the
-respective parts of the setup for DORiE.
-
-.. toctree::
-    :maxdepth: 1
-
-    install-prep
-    The README <readme>
-    cli
-    config-file
-    grid
-    parameter-file
-    bcfile

doc/python/index.rst

-Python Packages
-===============
-
-.. toctree::
-    :maxdepth: 1
-    :glob:
-
-    ./*