Small improvements to user manual

* Moved `COPYING.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `LICENSE` (download only) into user manual #177.
* Fixed formatting of GMSH command #177.
* Fixed various links in existing documentation.
* Updated link to user manual in CLI.
* Added hints on cook book to `README.md` and user manual index.
* Fix render of `README.md` tables in user manual.

COPYING.md

@@ -16,8 +16,8 @@
     You should have received a copy of the GNU General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-A copy of the [GNU General Public License](LICENSE) is distributed with the
-source code of this program.
+A copy of the [GNU General Public License Version 3](https://www.gnu.org/licenses/gpl-3.0.en.html)
+is distributed with the source code of this program.
 
 ## Copyright Holders
 

README.md

@@ -6,6 +6,10 @@ passive transport equation. The core feature is a C++ PDE-solver powered by
 [DUNE](https://dune-project.org/) and especially the
 [DUNE-PDELab](https://dune-project.org/modules/dune-pdelab/) module.
 
+Just getting started? Use the
+[Cook Book](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/cookbook/index.html)
+in the User Manual to dive right in!
+
 ### Contents of this README
 
 * [Overview](#overview)
@@ -42,7 +46,7 @@ in collaboration with
 [Interdisciplinary Center for Scientific Computing (IWR) Heidelberg](https://typo.iwr.uni-heidelberg.de/home/).
 
 DORiE is free software and licensed under the
-[GNU General Public License Version 3](LICENSE).
+[GNU General Public License Version 3](https://www.gnu.org/licenses/gpl-3.0.en.html).
 For the copyright notice and the list of copyright holders,
 see [`COPYING.md`](COPYING.md).
 
@@ -226,6 +230,7 @@ The specified versions are the _supported_ ones, where compatibility is ensured
 by CI tests.
 
 #### DUNE Packages
+
 | Software | Version/Branch | Comments |
 | ---------| -------------- | -------- |
 | [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6
@@ -241,6 +246,7 @@ by CI tests.
 | [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | *Optional:* For system tests
 
 #### DUNE Requirements
+
 | Software | Version/Branch | Comments |
 | ---------| -------------- | -------- |
 | CMake | 3.10.2 |
@@ -254,6 +260,7 @@ by CI tests.
 | SuperLU | 5.2 |
 
 #### DORiE Requirements
+
 | Software | Version/Branch | Comments |
 | ---------| -------------- | -------- |
 | [HDF5](https://www.hdfgroup.org/solutions/hdf5/) | 1.10 | MPI support required
@@ -264,6 +271,7 @@ by CI tests.
 | [Google Test](https://github.com/google/googletest) | `HEAD` | Included as Git Submodule
 
 #### Optional Packages
+
 | Software | Version/Branch | Comments |
 | -------- | -------------- | -------- |
 | [doxygen](http://www.stack.nl/~dimitri/doxygen/) | 1.8.13 | Builds documentation

doc/cookbook/index.rst

@@ -11,7 +11,7 @@ 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 </introduction/readme>` for
+installation. See the :doc:`installation manual </markdown/README>` for
 details. Additionally, install Paraview_ for analyzing the output.
 
 .. _Paraview: http://www.paraview.org/download/

doc/index.rst

@@ -3,15 +3,35 @@ DORiE Documentation
 
 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 free software and licensed under the `GNU General Public License v3.0
-<https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/blob/master/LICENSE>`_.
+DORiE is a DUNE module for solving the Richards equation, and optionally the
+passive transport equation for soil water flow.
+
+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 free software and licensed under the `GNU General Public License
+Version 3 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_. For further
+information, refer to the :doc:`markdown/COPYING`.
 
 DORiE complies to `Semantic Versioning <https://semver.org/>`_. Version number
 assignment and increment are based on the :doc:`public-api`.
 
+.. topic:: Just getting started?
+
+   Here's some information on how to proceed:
+
+   * The :doc:`/introduction/features` will show you which equations DORiE
+     solves and which models it offers.
+   * The :doc:`README </markdown/README>` contains information on how to set up
+     DORiE on your machine.
+   * Use the :doc:`Cook Book </cookbook/index>` to dive right into some
+     exemplary simulations!
+   * Consult the "Manual" section of you seek in-depth information on the single
+     features of DORiE.
+
+
 .. ifconfig:: not meta_ini_available
 
     .. warning::
@@ -24,7 +44,7 @@ assignment and increment are based on the :doc:`public-api`.
    :caption: Getting Started
 
    introduction/install-prep
-   The README <introduction/readme>
+   The README <markdown/README>
    introduction/features
    introduction/data-io
 
@@ -59,3 +79,13 @@ assignment and increment are based on the :doc:`public-api`.
    :glob:
 
    python/*
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Miscellaneous
+
+   Contribution Guide <markdown/CONTRIBUTING>
+   Code of Conduct <markdown/CODE_OF_CONDUCT>
+   Copyright Information <markdown/COPYING>
+
+* :download:`GNU General Public License v3.0 </markdown/LICENSE>`

doc/introduction/data-io.rst

@@ -10,7 +10,7 @@ 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/>`.
+has `Python bindings <https://pypi.org/project/vtk/>`_.
 
 Input Files
 ===========

doc/introduction/install-prep.rst

@@ -10,7 +10,8 @@ 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.
 
-Refer to :doc:`the ReadMe file <readme>` for installation instructions.
+Refer to :doc:`the ReadMe file </markdown/README>` for installation
+instructions.
 
 
 Prerequisites
@@ -62,7 +63,9 @@ 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
 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 </markdown/README>`.
 
 
 Windows

doc/manual/bcfile.rst

@@ -3,26 +3,28 @@ Boundary Conditions
 
 Boundary conditions represent the *super-scale physics*, the forcing of the
 (larger-scale) sourrounding system onto the simulated system.
-After specifying the :doc:`boundary segmentation <man-grid>`, we are able to
-define the actual conditions applied at each segment. Like the
-:doc:`parameterization data file <man-parameter-file>`, the boundary condition
-data file is a YAML_ file. Boundary segments are associated with their
-boundary conditions by means of the segment indices.
+After specifying the boundary segmentation when :doc:`creating and mapping a
+grid </manual/grid>`, we are able to define the actual conditions applied at
+each segment. Like the :ref:`parameterization data file <man-parameter_file>`,
+the boundary condition data file is a YAML_ file. Boundary segments are
+associated with their boundary conditions by means of the segment indices.
 
 .. contents::
     :depth: 3
     :local:
 
+.. _man-bc_file:
+
 Boundary Condition File
 -----------------------
 
 The file determines the boundary conditions at certain times for each boundary
 segment. Its file path must be given via the key ``boundary.file`` in the
-:doc:`config file <man-config-file>`.
+:doc:`config file </manual/config-file>`.
 
 After stating a certain boundary segment, the conditions are listed.
 The index is the boundary segment index specified in the
-:doc:`grid mapping <man-grid>`. A boundary condition generally consists of
+:doc:`grid mapping </manual/grid>`. A boundary condition generally consists of
 a type, a time interval, and a value. The latter two may be stated as sequences
 of values. This way, the time interval may be limited, or a boundary condition
 may be interpolated between the specified times. Certain types of boundary

doc/manual/grid.rst

@@ -150,9 +150,11 @@ load it into the GMSH GUI, or perform the meshing directly using the
 `GMSH command line interface
 <http://gmsh.info/doc/texinfo/gmsh.html#Non_002dinteractive-mode>`_:
 
+.. code-block:: bash
+
     gmsh <geo-file> -<dim>
 
-Replace ``<geo-file>`` with the appropriate file, and ``dim`` with the
+Replace ``<geo-file>`` with the appropriate file, and ``<dim?`` with the
 spatial dimension of the intended mesh.
 
 .. _HDF5: https://www.h5py.org/

doc/markdown/CODE_OF_CONDUCT.md

+../../CODE_OF_CONDUCT.md
\ No newline at end of file

doc/markdown/CONTRIBUTING.md

+../../CONTRIBUTING.md
\ No newline at end of file

doc/markdown/COPYING.md

+../../COPYING.md
\ No newline at end of file

doc/markdown/LICENSE

+../../LICENSE
\ No newline at end of file

doc/public-api.rst

@@ -15,8 +15,8 @@ respective configuration files are given in the
 :doc:`Config File Guide </manual/config-file>`.
 
 The main routine (`dorie run <config>`) also requires input files for
-:doc:`boundary conditions </manual/bcfile>` and
-:doc:`soil parameters <man-parameter_file>`.
+:ref:`boundary conditions <man-bc_file>` and
+:ref:`soil parameters <man-parameter_file>`.
 
 Code API
 ========
@@ -60,4 +60,4 @@ The coupling between Richards and Transport models is done by yet another
 model which is in charge of managing the steps of the two sub-models.
 
 .. doxygenclass:: Dune::Dorie::ModelTransport
-   :members:
\ No newline at end of file
+   :members:

doc/python/vtk_readers.rst

@@ -18,7 +18,7 @@ Prerequisites
 
 For using the modules and classes listed below, users need to install a set of
 required software packages. If you followed the installation instructions in
-the :doc:`ReadMe </introduction/readme>`, you are already set and can start
+the :doc:`ReadMe </markdown/README>`, you are already set and can start
 using them inside the :ref:`virtual environment <cli-venv>`.
 
 If you install the DORiE Python package separately, you may need to install the

python/dorie/dorie/cli/parser.py

@@ -12,8 +12,8 @@ def create_cl_parser():
     """
     parser = argparse.ArgumentParser(
         description="DORiE Command Line Interface\n"
-                    "For more information check our online documentation: "
-                    "http://dorie-doc.netlify.com.",
+                    "For more information check out our online documentation: "
+                    "https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/",
         epilog="DORiE  Copyright (C) 2019  DORiE Developers\n"
                "This program comes with ABSOLUTELY NO WARRANTY.\n"
                "This is free software, and you are welcome to redistribute it\n"