Restructure user docs

* Do not use DUNE CMake module for creating Sphinx docs anymore * Create subdirectories: manual, python, cookbook * Remove unused files * Remove 'Guided doxygen documentation' * Add symlink from doc/manual/ to README

Restructure user docs
* Do not use DUNE CMake module for creating Sphinx docs anymore * Create subdirectories: manual, python, cookbook * Remove unused files * Remove 'Guided doxygen documentation' * Add symlink from doc/manual/ to README
e1663417 · Lukas Riedel · b506eee7 · e1663417 · e1663417 · e1663417
Commit e1663417 authored Nov 12, 2018 by Lukas Riedel
22 changed files
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,7 @@
 build-cmake/

 # Exclude generated files
+doc/manual/config-file.rst
 python/dorie/wrapper/pf_from_file.py
 python/dorie/wrapper/test_dorie.py
 python/dorie/dorie/cli/cmds.py

--- a/README.md
+++ b/README.md
-# Welcome to DORiE!
+# DORiE README
 (**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.
@@ -8,7 +8,7 @@ The suite encapsulates a documentation and various tools for program setup, prog
 DORiE is developed and maintained by the [DORiE Developers](mailto:dorieteam@iup.uni-heidelberg.de) of the [TS-CCEES](http://ts.iup.uni-heidelberg.de/) research group at [IUP Heidelberg](http://www.iup.uni-heidelberg.de/), supervised by [Kurt Roth](http://ts.iup.uni-heidelberg.de/people/prof-dr-kurt-roth/), in collaboration with [Ole Klein](https://conan.iwr.uni-heidelberg.de/people/oklein/) and the [Scientific Computing Group](https://conan.iwr.uni-heidelberg.de/) of [IWR Heidelberg](https://typo.iwr.uni-heidelberg.de/home/).


-# Installation Instructions
+## Installation Instructions

 DORiE is a [DUNE](https://dune-project.org/) module and requires several other DUNE modules as well as third party software packages. Installation can be handled manually on your local machine, but for inexperienced users it is recommended to use the deployment software [Docker](https://www.docker.com/) instead.

@@ -18,7 +18,7 @@ directly to the the instructions on [how to execute DORiE](#run-dorie-run).
 The commands listed there are appended to the usual commands for running a
 Docker container. See the description on Docker Hub for further details.

-## Download Docker image
+### Download Docker image

 If you want to use any stable version of DORiE, or the most recent unstable
 version, you can download the appropriate images from Docker Hub. To do so,
@@ -32,7 +32,7 @@ refers to the latest stable version. You can download any tag by specifying
 the release tags list of the Git repository. The latest unstable version is
 tagged as `devel`.

-## Docker Installation
+### Docker Installation

 You can also compile any local version of DORiE into a new Docker image. To do
 so, execute
@@ -43,7 +43,7 @@ from within the top-level DORiE source directory. Docker will use a prepared
 image from Dockerhub and install DORiE into it. The created image will be called
 `<img>`.

-## Manual Installation
+### Manual Installation

 Installing all packages manually can be quite an effort, but useful for developers who want to have easy access to the source files or users who prefer to run DORiE without the Docker overhead.

@@ -53,7 +53,7 @@ DORiE is configured, built, and installed via the
 [DUNE Buildsystem](https://dune-project.org/doc/installation/), using the
 `dunecontrol` script to handle DUNE-internal dependencies.

-### Dependencies
+#### Dependencies
 Depending on your system configuration, there will be more packages necessary to
 install DORiE on your machine. See the step-by-step manual for further details.

@@ -86,7 +86,7 @@ by CI tests.
 | [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | master


-### Optional Packages
+#### Optional Packages
 | Software | Version/Branch | Comments |
 | ---------| -------------- | -------- |
 | [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | Handles system tests
@@ -95,7 +95,7 @@ by CI tests.
 | [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs


-### Step-by-step Instructions
+#### Step-by-step Instructions
 These instructions are suitable for a clean **Ubuntu** or **macOS** setup. The main difference between the two systems is the package manager. Debian-based systems have the APT manager already built in. On Mac, we recommend installing [Homebrew](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here.

 If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.html) on your machine, you don't need to install Python or Pip. Simply skip these packages when using the package managers for installing the software. However, notice the warnings when compiling DORiE below!
@@ -105,10 +105,10 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
        xcode-select --install

 2. Install third party packages:
-    
+
    **Ubuntu:**
-    
-        apt update 
+
+        apt update
        apt install cmake doxygen gcc g++ gfortran \
                    git libatlas-base-dev libfftw3-dev libfftw3-mpi-dev \
                    libfreetype6-dev libhdf5-mpi-dev libopenmpi-dev libpng-dev \
@@ -159,7 +159,7 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht

    to the `CMAKE_FLAGS` in the call to `dunecontrol` above.

-### Experimental Features
+#### Experimental Features
 The local operator implementing Richards equation's discretization supports
 multiple scheme settings. Setting these via the config file is disabled by
 default. You can enable this feature by reconfiguring DORiE with the CMake flag
@@ -169,16 +169,16 @@ The configuration settings in the section `[dg.experimental]` will then override
 the default settings.


-## Recommended Third-Party Software
+### Recommended Third-Party Software

 The following software packages are cross-platform, so you should be able to find a release that fits your operating system:

 * [Gmsh](http://gmsh.info/): An open-source CAD that can be used to create the `.msh` files used by DORiE to define triangular meshes.
 * [ParaView](http://www.paraview.org/): A powerful post-processing tool for VTK files. Offers both visualization and data analysis tools.

-# Usage
+## Usage

-## Documentation
+### Documentation

 The documentation of the latest release branch can be found [online](https://dorie-doc.netlify.com/).

@@ -193,14 +193,14 @@ or navigate to the `dorie/build-cmake` directory and call
 You will then find the index page of the documentation at
 `dorie/build-cmake/doc/html/index.html`.

-## Run, DORiE, Run!
+### Run, DORiE, Run!
 DORiE provides a command line interface (CLI) for all its functions.
 The required Python modules and all their dependencies are readily installed
 into a virtual environment (`venv`), which has to be activated within a
 shell session. You can do so by activating it in your current session
 (Manual Installation only) or by running the Docker application.

-### Run the `venv` using the Docker application
+#### Run the `venv` using the Docker application
 If you did not install DORiE locally, you can use the Docker
 application to boot up the virtual environment in a mounted directory of choice.

@@ -222,7 +222,7 @@ virtual environment activated.
 Notice, that you can only use **local file paths** in all configuration settings
 due to the directory mount.

-### Activate the `venv` locally
+#### Activate the `venv` locally
 To activate the virtual environment within your current shell session, execute

    source <path/to/>dorie/build-cmake/activate
@@ -241,7 +241,7 @@ terminal session!
 _With the virtual environment activated,_ you can now navigate to any directory
 that you would like to contain your simulation input and/or output data.

-### Execute the application
+#### Execute the application
 Any command to the DORiE application has the signature

    dorie <cmd> [<opts>] [<args>]
@@ -255,7 +255,7 @@ by calling

    dorie create

-DORiE implements a lightweight wrapper around the `dune-randomfield` 
+DORiE implements a lightweight wrapper around the `dune-randomfield`
 generator. You can use it to easily create a heterogeneous soil architecture.
 This step is optional. Tweak the parameters of `parfield.ini` to your liking
 and then call
@@ -274,12 +274,12 @@ Once prepared, call

 to execute the solver.

-## Troubleshooting
+### Troubleshooting
 CMake heavily caches the results of its configuration process. In case you encounter errors or strange behavior, especially after an update, you should delete the DORiE build folder (called `build-cmake` by default) and re-install DORiE using `dunecontrol`.

 If the problem persists, take a look at the [List of Known Bugs](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues), or create an issue yourself. For problems related to the installation, refer to the sections below.

-### Debugging
+#### Debugging
 DORiE can be built with debugging flags via CMake. To do so, run

    CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Debug" dunecontrol --only=dorie all
@@ -292,14 +292,7 @@ To re-create a release build, configure DORiE with the release build type by exe

    CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release" dunecontrol --only=dorie all

-#### Debugging inside Docker
-A debugger needs special security privileges usually not provided by the Docker engine. To enable debugging inside Docker, these privileges have to be granted when calling `docker run` by adding the options
-
-    --security-opt seccomp=unconfined
-
-The debugger `gdb` is pre-installed in the Docker container.
-
-### Running System Tests
+#### Running System Tests
 DORiE includes a testing system for comparing its results the ones of ODE solvers
 or former versions of itself. This ensures that DORiE is running correctly and
 producing the expected results. We distinguish _unit tests_ for testing certain
@@ -319,5 +312,5 @@ After building them with `Debug` flags and executing them, you can
 retrieve code coverage information using the
 [`gcovr`](https://gcovr.com/index.html) utility.

-### Further Help
+#### Further Help
 [Open an issue](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/new), or write to the [DORiE developer mailing list](mailto:dorieteam@iup.uni-heidelberg.de).
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
+#
+# .. cmake_function:: dorie_install_doc_utils
+#
+# Installs the software required for building the documentation
+# into the `venv`. Resets the cache entry `SPHINX_EXECUTABLE`
+# if it was found before and replaces it with the executable
+# installed into the `venv`.
+#
 function(dorie_install_doc_utils)
 	# install requirements into dune venv
 	set(INSTALL_CMD -m pip install -r ${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt)
@@ -23,31 +31,30 @@ dorie_install_doc_utils()
 add_subdirectory("doxygen")
 add_subdirectory("default_files")

-# copy static files to build tree
-file(COPY ${CMAKE_CURRENT_LIST_DIR}/examples DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
-file(COPY ${CMAKE_CURRENT_LIST_DIR}/figures DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
-file(COPY ${CMAKE_SOURCE_DIR}/README.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
-
-include(DuneSphinxCMakeDoc)
-dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
-	RST_SOURCES
-		index.rst
-		doxygen-guide.rst
-		logs-install.rst
-		other-cmake.rst
-		public-api.rst
-		python-dorie-wrapper.rst
-		python-dorie-parscraper.rst
-		python-dorie-testtools.rst
-		python-dorie-utilities.rst
-		man-bcfile.rst
-		man-cookbook.rst
-		man-installation.rst
-		man-config-file.rst
-		man-parameter-file.rst
-		man-grid.rst
-	MODULE_ONLY)
+file(RELATIVE_PATH
+	 CHEATSHEET_PFG_RELPATH
+	 ${CMAKE_CURRENT_SOURCE_DIR}/manual
+	 ${CMAKE_CURRENT_BINARY_DIR}/default_files/field-parameters.rst)
+file(RELATIVE_PATH
+	 CHEATSHEET_DORIE_RELPATH
+	 ${CMAKE_CURRENT_SOURCE_DIR}/manual
+	 ${CMAKE_CURRENT_BINARY_DIR}/default_files/parameters.rst)
+configure_file(manual/config-file.rst.in
+			   ${CMAKE_CURRENT_SOURCE_DIR}/manual/config-file.rst)
+
+
+configure_file(conf.py.in conf.py)
+
+add_custom_target(sphinx_html
+	COMMAND ${SPHINX_EXECUTABLE}
+			-T -b html
+			-c ${CMAKE_CURRENT_BINARY_DIR} # conf.py dir
+			-d ${CMAKE_CURRENT_BINARY_DIR}/_doctrees # doctree pickles dir
+			${CMAKE_CURRENT_SOURCE_DIR} # input dir
+			${CMAKE_CURRENT_BINARY_DIR}/html # output dir
+)

 if(TARGET sphinx_html)
  add_dependencies(sphinx_html doxygen_dorie)
+  add_dependencies(doc sphinx_html)
 endif()
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -16,7 +16,7 @@
 import sys
 import os
 import shlex
-import recommonmark
+# import recommonmark
 from recommonmark.parser import CommonMarkParser
 from recommonmark.transform import AutoStructify

@@ -53,9 +53,9 @@ extensions = [
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
-    'sphinx_cmake_dune',
    'sphinxarg.ext',
-    'breathe'
+    'breathe',
+    'recommonmark'
 ]

 # Path to local MathJax JS file (set through CMake)
@@ -70,7 +70,7 @@ templates_path = ['_templates']

 # specify custom source parsers
 source_parsers = {
-   '.md': 'recommonmark.parser.CommonMarkParser',
+   '.md': CommonMarkParser,
 }

 # The suffix(es) of source filenames.
@@ -81,8 +81,8 @@ source_suffix = ['.rst', '.md']
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'

-# The master toctree document.
-master_doc = 'index'
+# The master toctree document. (defaults to 'contents')
+master_doc = 'contents'

 # General information about the project.
 project = 'DORiE'
@@ -338,4 +338,4 @@ def setup(app):
    app.add_config_value('deploy_mode', '', 'env')
    app.add_config_value('recommonmark_config', {
            }, True)
-    app.add_transform(AutoStructify)
\ No newline at end of file
+    app.add_transform(AutoStructify)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,18 +19,10 @@ 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 :ref:`quickstart`.
-If you have already installed DORiE, jump straight to the :doc:`man-cookbook`
+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!

-You might also want to have a look at both the :doc:`man-config-file`
-and :doc:`man-bcfile`, explaining all input parameters and boundary condition
-files, respectively.
-
-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`.

@@ -45,38 +37,10 @@ Manual
 .. toctree::
   :maxdepth: 1

-   man-installation
-   python-dorie-wrapper
-   man-config-file
-   man-grid
-   man-bcfile
-   man-cookbook
-   man-parameter-file
+   manual/index
   public-api
-
-.. _c-reference:
-
-C++ Package Reference
---------------------
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   doxygen-*
-
-.. _python-reference:
-
-Python Package Reference
------------------------
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   python-*
-
-.. _cmake-reference:
+   cookbook/index
+   python/index


 Indices and tables

--- a/doc/man-cookbook.rst
+++ b/doc/man-cookbook.rst
@@ -24,16 +24,16 @@ be retrieved!
 Input Files
 ^^^^^^^^^^^
 Templates for the required files can conveniently be generated with the
-:doc:`CLI <python-dorie-wrapper>`.
+:doc:`CLI </manual/cli>`.

-* :doc:`Configuration File <man-config-file>` (``.ini``):
+* :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 <man-bcfile>` (``.bcdat``):
+* :doc:`Boundary Condition Data File </manual/bcfile>` (``.bcdat``):
  Specifies the boundary segmentation and the boundary conditions.
  Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``

@@ -44,7 +44,7 @@ Templates for the required files can conveniently be generated with the
  Used to generate heterogeneous soil architectures and boundary segmentations
  for rectangular grids.

-* :ref:`Scaling Field H5 Files <man-parameter_sclaing>` (optional):
+* :ref:`Scaling Field H5 Files <man-parameter_scaling>` (optional):
  Datasets for interpolating local heterogeneities in the parameterization.

 Output Files

--- a/doc/doxygen-guide.rst
+++ b/doc/doxygen-guide.rst
-Guided Doxygen Documentation
-****************************
-
-.. contents::
-   :depth: 3
-
-
-Introduction
-============
-This documentation includes the documentation created by Doxygen, and enhances it by adding further overview features and explanations not suitable for inclusion in the source code.
-
-DORiE consists of several thousand lines of C++ source code, not accounting for the DUNE functions and classes included in the program. There are two approaches on getting to know the code, first by following the programs course fairly linearly, and second by studying class functions and interactions via the modules overview. - Don't worry! The modularity of the code enables you to work with portions of it while neglecting other parts.
-
-Programming Philosophy
----------------------
-DORiE makes high use of object oriented programming by constructing different classes and letting them interact quite independently.
-
-In general, the constructor of every class reads the parameters important to the same class and immediately assembles all variables and functions needed for further use. Class constructors usually do not receive parameters explicitly, but read them from the parameter file independently. This improves readability of the code but can cause conflicts in parameter declarations. The :doc:`python-dorie-parscraper` makes sure that all parameter queries are consistent before DORiE is compiled.
-
-Query functions are handled in a top-down approach, where requests for and the sending of data are initiated by the higher-order or owner class. Ownership itself, however, is intended to be as flat as possible, with the main program functions assembling most of the classes and handing them over to other classes with which they interact.
-
-
-Programming Guide
-----------------
-None so far.
-
-
-.. _code-guide:
-DORiE Routine
-=============
-
-.. _code-main:
-Main Function
-------------
-The Main Routine of DORiE creates a Parameter File Parser object, to read out the parameter file.
-It assembles a Dune::Grid object by calling the appropriate functions for a structured rectangular
-or an unstructured simplex grid. The latter is created from a Gmsh :file:`.msh` Mesh data file.
-
-The grid is handed over to the appropriate Solver functions, which build the Dune Grid Function Space
-for a rectangular or simplex grid, respectively. The Solver helper functions then call the actual :ref:`code-solver`
-for computing the solution.
-
-.. doxygenfile:: dorie.cc
-
-.. doxygenfunction:: build_grid_gmsh
-
-.. doxygenfunction:: build_grid_cube
-
-.. _code-solver:
-Simulation
----------
-The Simulation template receives the assembled Grid Function Space and initializes the PDELab Backends
-to compute the solution.
-
-.. doxygenclass:: Dune::Dorie::RichardsSimulation
-
-.. _code-param:
-Richards Equation Classes
-------------------------
-To compute the solution, the various parts of the Richards Equation and the chosen parameterization
-have to be represented. This is achieved by building objects which provide appropriate queries for
-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::ParameterizationBase
-   :members:
-
-.. doxygenclass:: Dune::Dorie::MualemVanGenuchten
-   :members:
-
-.. doxygenclass:: Dune::Dorie::FlowBoundary
-   :members:
-
-.. doxygenclass:: Dune::Dorie::FlowSource
-   :members:
-
-.. _code-operator:
-Richards Equation Local Operators
---------------------------------
-The local operators bind to the PDELab backend and compute the local residual along quadrature points on the grid.
-They represent the numeric implementation of the PDE's *strong formulation*.
-DORiE uses the mass conserving Discontinuous Galerkin (DG) discretization scheme.
-
-.. doxygenclass:: Dune::Dorie::Operator::RichardsDGSpatialOperator
-   :members:
-
-.. doxygenclass:: Dune::Dorie::Operator::RichardsDGTemporalOperator
-   :members:
-
-.. _code-controller:
-Time Step Controller
--------------------
-The time step interval is controlled by an own class. It is adjusted according to the performance of the
-non-linear Newton Solver and possible changes in the boundary conditions.
-
-.. doxygenclass:: Dune::Dorie::CalculationController
-   :members:
-
-.. _code-adaptivity:
-Adaptive Grid Refinement
------------------------
-If enabled, adaptive grid refinement is applied after a time step has been computed successfully.
-Similar to the actual solver, the Adaptivity Controller implements a Local Operator which computes
-local residuals along the grid. The residual represents the estimated error of the solution based
-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::Operator::FluxErrorEstimator
-   :members:
-
-.. doxygenclass:: Dune::Dorie::AdaptivityHandler
-   :members:
--- a/doc/logs-install.rst
+++ b/doc/logs-install.rst
-################
-installation.log
-################
-
-The following document is a log file of the complete installation on our integration server.
-It provides a rough reference to what the output of ``doriecontrol install all`` should
-look like, in case you suspect anything to be wrong with your installation.
-
-.. include:: logs/installation.log
-    :literal:
--- a/doc/man-bcfile.rst
+++ b/doc/man-bcfile.rst
@@ -87,7 +87,7 @@ These lines follow a simple grammar:

 The boundary conditions defined here are parsed in the same order as the boundary segments have been specified. In 3D, the rectangular boundary segments are parsed in a tabular fashion, where columns run faster than rows. Columns are defined along the first direction specified in the `Boundary Segmentation`_, and rows are defined along the second direction.

-.. figure:: figures/man-bcfile-segm1.png
+.. figure:: /figures/man-bcfile-segm1.png
 	:width: 40 %
 	:align: left

@@ -111,13 +111,13 @@ Simple Boundary Condition datafiles can be created with the command ``dorie crea
 Exemplary BC File for Infiltration (2D)
 ---------------------------------------

-    .. include:: default_files/2d_infiltr.bcdat
+    .. include:: /default_files/2d_infiltr.bcdat
      :code: ini

 Exemplary BC File for Infiltration (3D)
 ---------------------------------------

-    .. include:: default_files/3d_infiltr.bcdat
+    .. include:: /default_files/3d_infiltr.bcdat
      :code: ini

 Code Documentation

--- a/doc/python-dorie-wrapper.rst
+++ b/doc/python-dorie-wrapper.rst
@@ -87,4 +87,4 @@ instance used for the CLI.

 .. argparse::
    :ref: dorie.cli.parser.create_cl_parser
-    :prog: dorie
\ No newline at end of file
+    :prog: dorie
--- a/doc/man-config-file.rst
+++ b/doc/man-config-file.rst
@@ -37,7 +37,7 @@ A set of rules defines this syntax:
   is equivalent with

   .. code-block:: none
-	
+
 		heading1.heading2.key1.key2 = value
 		heading1.heading2.key1.key3 = value

@@ -48,21 +48,21 @@ Cheat Sheets
 ============

 These cheat sheets are automatically generated by
-:doc:`the Parameter Scraper <python-dorie-parscraper>`.
+:doc:`the Parameter Scraper </python/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>`.
+:doc:`CLI documentation </manual/cli>`.

 Parameter Field Generator
 -------------------------

-.. include:: default_files/field-parameters.rst
+.. include:: @CHEATSHEET_PFG_RELPATH@


 Main Routine
 ------------

-Common and richards parameters are needed in the configuration file. 
+Common and richards parameters are needed in the configuration file.

-.. include:: default_files/parameters.rst
+.. include:: @CHEATSHEET_DORIE_RELPATH@
--- a/doc/man-grid.rst
+++ b/doc/man-grid.rst
 Grid Creation and Mapping
 =========================

-To guarantee numeric accuracy, :doc:`boundary conditions <man-bcfile>`
-and :doc:`parameterizations <man-parameter-file>` must exactly map to grid
+To guarantee numeric accuracy, :doc:`boundary conditions <bcfile>`
+and :doc:`parameterizations <parameter-file>` must exactly map to grid
 boundary faces and grid cells, respectively. DORiE therefore not only requires
 a specification of the actual grid, but also of these mappings.

@@ -102,7 +102,7 @@ that the left and right boundaries consist of two *geometric* lines each.
 This code can directly be transferred to a Python script using
 the pygmsh_ module. It writes a ``.geo`` file while checking for a correct
 syntax within your script. It is readily installed into the
-:doc:`virtual environment <python-dorie-wrapper>`.
+:doc:`virtual environment <cli>`.

 .. code-block:: default


--- a/doc/manual/index.rst
+++ b/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
--- a/doc/man-installation.rst
+++ b/doc/man-installation.rst
-############
-Installation
-############
+*************************
+Installation Preparations
+*************************

 .. contents::

-.. _readme:
-***********
-ReadMe File
-***********
-
-.. toctree::
-  :maxdepth: 1
+You can build DORiE locally on your machine for maximum performance. This requires you to take care of all dependencies and to handle the installation process yourself. On the other hand, you can use a virtual environment to run DORiE. We support this feature by using `Docker <https://www.docker.com/>`_.
+You can install your local DORiE source code into a Docker image or load a
+prepared image from `Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_.
+You can then run the application as Docker container. Depending on your
+operating system, this will lead to impared performance.

-  README
+Refer to :doc:`the ReadMe file <readme>` for installation instructions.

-************
-Preparations
-************

 Prerequisites
 =============
@@ -51,22 +46,6 @@ in the terminal. By default, the remote host will be called ``origin``, and the
 from a terminal inside the repository folder. Refer to the `Atlassian Git Tutorial <https://www.atlassian.com/git>`_ for more information on using Git.


-.. _installation:
-************
-Installation
-************
-
-You can build DORiE locally on your machine for maximum performance. This requires you to take care of all dependencies and to handle the installation process yourself. On the other hand, you can use a virtual environment to run DORiE. We support this feature by using `Docker <https://www.docker.com/>`_.
-You can install your local DORiE source code into a Docker image or load a
-prepared image from `Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_.
-You can then run the application as Docker container. Depending on your
-operating system, this will lead to impared performance.
-
-Follow the Installation Instructions in the :doc:`the ReadMe <README>` for installing DORiE.
-
-Notice also the instructions below for setting up your computer to meet the most basic requirements to run DORiE.
-
-
 OS-Dependent Configuration
 ==========================

@@ -93,16 +72,16 @@ XCode for the first time, or you can simply execute

 in the terminal.

-You are now ready to :ref:`install DORiE <installation>`.
+You are now ready to instal DORiE.


 Linux
 -----
 Since there is a multitude of different Linux distributions, we cannot provide
 installation instructions for all of them. DORiE is regularly tested on the latest stable version of Ubuntu, so if you are running this OS, you may proceed with the
-:ref:`installation <installation>` right away.
+installation right away.

-On any other distribution, the procedure of installing dependencies might differ from the step-by-step instructions supplied in :doc:`the ReadMe <README>`.
+On any other distribution, the procedure of installing dependencies might differ from the step-by-step instructions supplied in :doc:`the ReadMe <readme>`.


 Windows

--- a/doc/man-parameter-file.rst
+++ b/doc/man-parameter-file.rst
@@ -2,7 +2,7 @@ Soil Parameterization
 =====================

 Specifying the domain properties requires input of the
-:doc:`soil architecture <man-grid>`
+:doc:`soil architecture <grid>`
 (in relation to the grid) and of the soil parameters. The latter incorporate
 the *subscale physics*, the representation of the soil hydraulic properties
 below the REV scale. DORiE requires several input files for retrieving this
@@ -16,7 +16,7 @@ given in the config file.
 Additionally, you can specify settings for the small-scale heterogeneities
 of the soil. They require an input via H5 datasets that contain appropriate
 scaling factors. You can conveniently create such datasets using the random
-field generator of the :doc:`command line interface <python-dorie-wrapper>`.
+field generator of the :doc:`command line interface </manual/cli>`.

 .. _man-parameter_file:

@@ -25,7 +25,7 @@ YAML Parameter File
 This file is used to specify the parameterization for each medium inside the
 simulated domain. It follows a simple hierarchical syntax. The file path and
 name must be specified via the ``parameters.file`` key of the
-:doc:`config file <man-config-file>`.
+:doc:`config file <config-file>`.

 The top-level mapping must contain the key ``volumes``. This key contains a
 sequence of arbitrary parameterization names. These, in turn, contain the
@@ -74,7 +74,7 @@ The parameterization ``type`` must match the static ``type`` member of one of
 them. Likewise, the parameters must match the names of parameters
 these objects use.