Commit 007a289e authored by Lukas Riedel's avatar Lukas Riedel 📝 Committed by Santiago Ospina De Los Ríos

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.
parent 4b6566b3
...@@ -16,8 +16,8 @@ ...@@ -16,8 +16,8 @@
You should have received a copy of the GNU General Public License You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>. 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 A copy of the [GNU General Public License Version 3](https://www.gnu.org/licenses/gpl-3.0.en.html)
source code of this program. is distributed with the source code of this program.
## Copyright Holders ## Copyright Holders
......
...@@ -6,6 +6,10 @@ passive transport equation. The core feature is a C++ PDE-solver powered by ...@@ -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](https://dune-project.org/) and especially the
[DUNE-PDELab](https://dune-project.org/modules/dune-pdelab/) module. [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 ### Contents of this README
* [Overview](#overview) * [Overview](#overview)
...@@ -42,7 +46,7 @@ in collaboration with ...@@ -42,7 +46,7 @@ in collaboration with
[Interdisciplinary Center for Scientific Computing (IWR) Heidelberg](https://typo.iwr.uni-heidelberg.de/home/). [Interdisciplinary Center for Scientific Computing (IWR) Heidelberg](https://typo.iwr.uni-heidelberg.de/home/).
DORiE is free software and licensed under the 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, For the copyright notice and the list of copyright holders,
see [`COPYING.md`](COPYING.md). see [`COPYING.md`](COPYING.md).
...@@ -226,6 +230,7 @@ The specified versions are the _supported_ ones, where compatibility is ensured ...@@ -226,6 +230,7 @@ The specified versions are the _supported_ ones, where compatibility is ensured
by CI tests. by CI tests.
#### DUNE Packages #### DUNE Packages
| Software | Version/Branch | Comments | | Software | Version/Branch | Comments |
| ---------| -------------- | -------- | | ---------| -------------- | -------- |
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6 | [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6
...@@ -241,6 +246,7 @@ by CI tests. ...@@ -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-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | *Optional:* For system tests
#### DUNE Requirements #### DUNE Requirements
| Software | Version/Branch | Comments | | Software | Version/Branch | Comments |
| ---------| -------------- | -------- | | ---------| -------------- | -------- |
| CMake | 3.10.2 | | CMake | 3.10.2 |
...@@ -254,6 +260,7 @@ by CI tests. ...@@ -254,6 +260,7 @@ by CI tests.
| SuperLU | 5.2 | | SuperLU | 5.2 |
#### DORiE Requirements #### DORiE Requirements
| Software | Version/Branch | Comments | | Software | Version/Branch | Comments |
| ---------| -------------- | -------- | | ---------| -------------- | -------- |
| [HDF5](https://www.hdfgroup.org/solutions/hdf5/) | 1.10 | MPI support required | [HDF5](https://www.hdfgroup.org/solutions/hdf5/) | 1.10 | MPI support required
...@@ -264,6 +271,7 @@ by CI tests. ...@@ -264,6 +271,7 @@ by CI tests.
| [Google Test](https://github.com/google/googletest) | `HEAD` | Included as Git Submodule | [Google Test](https://github.com/google/googletest) | `HEAD` | Included as Git Submodule
#### Optional Packages #### Optional Packages
| Software | Version/Branch | Comments | | Software | Version/Branch | Comments |
| -------- | -------------- | -------- | | -------- | -------------- | -------- |
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | 1.8.13 | Builds documentation | [doxygen](http://www.stack.nl/~dimitri/doxygen/) | 1.8.13 | Builds documentation
......
...@@ -11,7 +11,7 @@ Prerequisites ...@@ -11,7 +11,7 @@ Prerequisites
You need a working application. You can either use the image shipped via 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 `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. details. Additionally, install Paraview_ for analyzing the output.
.. _Paraview: http://www.paraview.org/download/ .. _Paraview: http://www.paraview.org/download/
......
...@@ -3,15 +3,35 @@ DORiE Documentation ...@@ -3,15 +3,35 @@ DORiE Documentation
Welcome to the DORiE Documentation! Welcome to the DORiE Documentation!
DORiE is a DUNE module for solving the Richards equation. The source code is DORiE is a DUNE module for solving the Richards equation, and optionally the
available from the `public repository <https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie>`_. passive transport equation for soil water flow.
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 The source code is available from the
<https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/blob/master/LICENSE>`_. `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 DORiE complies to `Semantic Versioning <https://semver.org/>`_. Version number
assignment and increment are based on the :doc:`public-api`. 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 .. ifconfig:: not meta_ini_available
.. warning:: .. warning::
...@@ -24,7 +44,7 @@ assignment and increment are based on the :doc:`public-api`. ...@@ -24,7 +44,7 @@ assignment and increment are based on the :doc:`public-api`.
:caption: Getting Started :caption: Getting Started
introduction/install-prep introduction/install-prep
The README <introduction/readme> The README <markdown/README>
introduction/features introduction/features
introduction/data-io introduction/data-io
...@@ -59,3 +79,13 @@ assignment and increment are based on the :doc:`public-api`. ...@@ -59,3 +79,13 @@ assignment and increment are based on the :doc:`public-api`.
:glob: :glob:
python/* 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>`
...@@ -10,7 +10,7 @@ easily be written using the h5py_ Python module. ...@@ -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 DORiE writes output files in the VTK_ format, a filetype suitable for storing
grid-based datasets. These files can be evaluated interactively using grid-based datasets. These files can be evaluated interactively using
Paraview_. The VTK software library can be included into C++ code and even 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 Input Files
=========== ===========
......
...@@ -10,7 +10,8 @@ prepared image from `Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_. ...@@ -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 You can then run the application as Docker container. Depending on your
operating system, this will lead to impared performance. 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 Prerequisites
...@@ -62,7 +63,9 @@ Since there is a multitude of different Linux distributions, we cannot provide ...@@ -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 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. 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 Windows
......
...@@ -3,26 +3,28 @@ Boundary Conditions ...@@ -3,26 +3,28 @@ Boundary Conditions
Boundary conditions represent the *super-scale physics*, the forcing of the Boundary conditions represent the *super-scale physics*, the forcing of the
(larger-scale) sourrounding system onto the simulated system. (larger-scale) sourrounding system onto the simulated system.
After specifying the :doc:`boundary segmentation <man-grid>`, we are able to After specifying the boundary segmentation when :doc:`creating and mapping a
define the actual conditions applied at each segment. Like the grid </manual/grid>`, we are able to define the actual conditions applied at
:doc:`parameterization data file <man-parameter-file>`, the boundary condition each segment. Like the :ref:`parameterization data file <man-parameter_file>`,
data file is a YAML_ file. Boundary segments are associated with their the boundary condition data file is a YAML_ file. Boundary segments are
boundary conditions by means of the segment indices. associated with their boundary conditions by means of the segment indices.
.. contents:: .. contents::
:depth: 3 :depth: 3
:local: :local:
.. _man-bc_file:
Boundary Condition File Boundary Condition File
----------------------- -----------------------
The file determines the boundary conditions at certain times for each boundary 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 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. After stating a certain boundary segment, the conditions are listed.
The index is the boundary segment index specified in the 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 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 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 may be interpolated between the specified times. Certain types of boundary
......
...@@ -150,9 +150,11 @@ load it into the GMSH GUI, or perform the meshing directly using the ...@@ -150,9 +150,11 @@ load it into the GMSH GUI, or perform the meshing directly using the
`GMSH command line interface `GMSH command line interface
<http://gmsh.info/doc/texinfo/gmsh.html#Non_002dinteractive-mode>`_: <http://gmsh.info/doc/texinfo/gmsh.html#Non_002dinteractive-mode>`_:
.. code-block:: bash
gmsh <geo-file> -<dim> 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. spatial dimension of the intended mesh.
.. _HDF5: https://www.h5py.org/ .. _HDF5: https://www.h5py.org/
......
../../CODE_OF_CONDUCT.md
\ No newline at end of file
../../CONTRIBUTING.md
\ No newline at end of file
../../COPYING.md
\ No newline at end of file
../../LICENSE
\ No newline at end of file
...@@ -15,8 +15,8 @@ respective configuration files are given in the ...@@ -15,8 +15,8 @@ respective configuration files are given in the
:doc:`Config File Guide </manual/config-file>`. :doc:`Config File Guide </manual/config-file>`.
The main routine (`dorie run <config>`) also requires input files for The main routine (`dorie run <config>`) also requires input files for
:doc:`boundary conditions </manual/bcfile>` and :ref:`boundary conditions <man-bc_file>` and
:doc:`soil parameters <man-parameter_file>`. :ref:`soil parameters <man-parameter_file>`.
Code API Code API
======== ========
...@@ -60,4 +60,4 @@ The coupling between Richards and Transport models is done by yet another ...@@ -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. model which is in charge of managing the steps of the two sub-models.
.. doxygenclass:: Dune::Dorie::ModelTransport .. doxygenclass:: Dune::Dorie::ModelTransport
:members: :members:
\ No newline at end of file
...@@ -18,7 +18,7 @@ Prerequisites ...@@ -18,7 +18,7 @@ Prerequisites
For using the modules and classes listed below, users need to install a set of 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 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>`. using them inside the :ref:`virtual environment <cli-venv>`.
If you install the DORiE Python package separately, you may need to install the If you install the DORiE Python package separately, you may need to install the
......
...@@ -12,8 +12,8 @@ def create_cl_parser(): ...@@ -12,8 +12,8 @@ def create_cl_parser():
""" """
parser = argparse.ArgumentParser( parser = argparse.ArgumentParser(
description="DORiE Command Line Interface\n" description="DORiE Command Line Interface\n"
"For more information check our online documentation: " "For more information check out our online documentation: "
"http://dorie-doc.netlify.com.", "https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/",
epilog="DORiE Copyright (C) 2019 DORiE Developers\n" epilog="DORiE Copyright (C) 2019 DORiE Developers\n"
"This program comes with ABSOLUTELY NO WARRANTY.\n" "This program comes with ABSOLUTELY NO WARRANTY.\n"
"This is free software, and you are welcome to redistribute it\n" "This is free software, and you are welcome to redistribute it\n"
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment