Commit c7099e2c authored by Lukas Riedel's avatar Lukas Riedel

Merge branch 'feature/sphinx-doc-fix' into 'master'

make documentation work again

Closes #10 and #5

See merge request !10
parents b210151d 555d513b
......@@ -92,16 +92,14 @@ Depending on your system configuration, there will be more packages necessary to
| [dune-functions](https://gitlab.dune-project.org/staging/dune-functions) | releases/2.5
| [dune-typetree](https://gitlab.dune-project.org/staging/dune-typetree) | releases/2.5
| [dune-pdelab](https://gitlab.dune-project.org/pdelab/dune-pdelab) | releases/2.5
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | master
| [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | master
### Optional Packages
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | master | Handles system tests
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | | Builds documentation
| [Sphinx](http://www.sphinx-doc.org/en/stable/) | | Builds documentation
| [Breathe](https://github.com/michaeljones/breathe) | | Builds documentation
| [METIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 5 | For parallel runs
| [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs
......@@ -139,11 +137,6 @@ These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. Th
**Parallel runs without these two packages are possible but not supported!**
2. Install the necessary Python packages using `pip`:
pip3 install --upgrade pip
pip3 install sphinx breathe
3. **Mac OS X** only:
The Apple Clang compiler shipped with CMake is not suitable for compiling DORiE. Before proceeding, call
......
message(STATUS "Python modules path: ${DORIE_PYTHON_MODULES}")
function(dorie_install_doc_utils)
# install requirements into dune venv
set(INSTALL_CMD -m pip install -r ${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt)
dune_execute_process(COMMAND "${DUNE_PYTHON_VIRTUALENV_EXECUTABLE}" "${INSTALL_CMD}"
ERROR_MESSAGE "dune_python_install_package: Error installing doc utilities into virtualenv!")
# find Sphinx in dune venv directory
unset(SPHINX_EXECUTABLE CACHE)
find_program(SPHINX_EXECUTABLE
NAMES sphinx-build
PATHS ${DUNE_PYTHON_VIRTUALENV_PATH}/bin
NO_DEFAULT_PATH)
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(
"Sphinx"
DEFAULT_MSG
SPHINX_EXECUTABLE
)
endfunction()
dorie_install_doc_utils()
add_subdirectory("doxygen")
add_subdirectory("default_files")
......@@ -6,9 +26,27 @@ 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()
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
python-dorie-wrapper.rst
python-dorie-parscraper.rst
python-dorie-testtools.rst
python-dorie-utilities.rst
quickstart-bcfile.rst
quickstart-cookbook.rst
quickstart-installation.rst
quickstart-parameters.rst
MODULE_ONLY)
if(TARGET sphinx_html)
add_dependencies(sphinx_html doxygen_dorie)
endif()
......@@ -16,6 +16,9 @@
import sys
import os
import shlex
import recommonmark
from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
......@@ -30,10 +33,6 @@ rst_prolog = """
.. |branch| replace:: @DEPLOY_SPHINX_GITBRANCH@
"""
def setup(app): # pass this along
app.add_config_value('deploy_mode', '', 'env')
sys.path.append('@DUNE_SPHINX_EXT_PATH@')
#python_modules = '@DORIE_PYTHON_MODULES@'
......@@ -68,10 +67,15 @@ else:
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# specify custom source parsers
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
source_suffix = ['.rst', '.md']
# The encoding of source files.
#source_encoding = 'utf-8-sig'
......@@ -145,7 +149,7 @@ todo_include_todos = True
try:
from sphinx import version_info
if version_info[0:2] > (1,2):
html_theme = 'haiku'
html_theme = 'sphinx_rtd_theme'
except Exception as _: pass
# Theme options are theme-specific and customize the look and feel of a theme
......@@ -325,3 +329,11 @@ texinfo_documents = [
breathe_projects = { "dorie": "@CMAKE_CURRENT_BINARY_DIR@/doxygen/xml" }
breathe_default_project = "dorie"
# -- Pass special options to build setup ---------------------------------
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
......@@ -44,7 +44,7 @@ Quick Start
.. _c-reference:
C++ package reference
C++ Package Reference
---------------------
.. toctree::
......@@ -55,7 +55,7 @@ C++ package reference
.. _python-reference:
Python package reference
Python Package Reference
------------------------
.. toctree::
......@@ -66,29 +66,9 @@ Python package reference
.. _cmake-reference:
Other parts of DORiE
---------------------
.. toctree::
:maxdepth: 1
:glob:
other-*
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Build logs
==========
.. toctree::
:maxdepth: 2
logs-install
logs-testing
......@@ -63,33 +63,34 @@ dorie.utilities.grid
:members:
:undoc-members:
dorie.utilities.fuzzy_compare
-----------------------------
dorie.utilities.fuzzy_compare_grid
----------------------------------
.. automodule:: dorie.utilities.fuzzy_compare
.. automodule:: dorie.utilities.fuzzy_compare_grid
:members:
:undoc-members:
dorie.utilities.vtk_grabber
---------------------------
dorie.utilities.vtktools.vtkfile
------------------------------------
.. automodule:: dorie.utilities.vtk_grabber
.. automodule:: dorie.utilities.vtktools.vtkfile
:members:
:undoc-members:
dorie.utilities.vtk_reader
--------------------------
dorie.utilities.vtktools.vtk_grabber
------------------------------------
.. automodule:: dorie.utilities.vtk_reader
.. automodule:: dorie.utilities.vtktools.vtk_grabber
:members:
:undoc-members:
dorie.utilities.vtk_plotter
---------------------------
.. automodule:: dorie.utilities.vtk_plotter
dorie.utilities.vtktools.pvd_reader
-----------------------------------
.. automodule:: dorie.utilities.vtktools.pvd_reader
:members:
:undoc-members:
dorie.utilities._load_all_in_folder
-----------------------------------
......
********************
DORiE Wrapper Script
********************
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:
.. object:: dorie.py
The script is technically a Python script but can be executed with a simple `./dorie` command.
.. option:: dorie create
This command creates input files for executing DORiE. They are set up with the default values supplied by the :doc:`Parameter Scraper <dorie.parscraper>` and have to be adapted for the first program run.
.. option:: pfg <config>
Execute the DORiE Parameter Field Generator. Given a config file (default: `parfield.ini`), this command will create a parameter field file in the H5 format representing the soil architecture for the simulation.
.. option:: run <config>
Execute the DORiE PDE solver. Depending on the options given in the config file (default: `config.ini`), the command will execute the main solver routine.
.. option:: plot <vtk>
Call the Python plotting script on a single `.vtk` file. Prints the values of the specified (or all) variables into `.png`files.
.. option:: -h
Print help messages. This option can be combined with all other options for details on how to formulate the command and its arguments
......@@ -25,7 +25,7 @@ DORiE Output Files
------------------
DORiE places its output into the directory defined at ``output.outputPath``.
* **Time Stamp File:** (:file:`.pvd`) Containing the time information for the respective VTK output files. Load this file into Paraview_ to analyze the entire output of DORiE. Due to `a bug in the program <http://shangrila.iup.uni-heidelberg.de:30000/dorie/dorie/issues/89>`_, this file is always saved in the directory from which DORiE is executed!
* **Time Stamp File:** (:file:`.pvd`) Containing the time information for the respective VTK output files. Load this file into Paraview_ to analyze the entire output of DORiE. This file is always saved in the directory from which DORiE is executed!
* **VTK Output Files:** (:file:`.vtu`) Containing the grid and the solution for a single time step. The solution contains information on the Matric Head (``head``, scalar), the Volumetric Water Content (``theta_w``, scalar), the Water Saturation (``Theta``, scalar), the Volumetric Water Flux (``flux``, vector), and the Saturated Hydrolic Conductivity (``K_0``, scalar). The files can be visualized using Paraview_ or the :ref:`DORiE VTK Parser <plot_vtk>`.
* *Optional* **Random Field Data** (:file:`.h5` or :file:`.dat`) Information on the Random Field created for a run. If the ``randomField`` values match the ones of the saved files, the Random Field is loaded from these files instead of being computed again.
* *Optional* **Parallel Collection Files** (:file:`.pvtu`) Containing information on combining :file:`.vtu`-files from different processes, if DORiE was executed in parallel (feature pending).
......
============
############
Installation
============
############
.. contents::
.. _readme:
***********
ReadMe File
***********
.. toctree::
:maxdepth: 1
README
************
Preparations
************
Prerequisites
#############
=============
To install and run DORiE, your computer needs to meet the following requirements:
- 64-bit version of Linux or OSX
- 64-bit version of Linux, macOS, or Windows
- Intel i5 processor or equivalent
- Intel i3/5/7 2xxx processor with at least two cores, or equivalent
- at least 4GB of RAM (8GB or more recommended)
- 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@shangrila.iup.uni-heidelberg.de:30001/dorie/dorie.git
git clone ssh://git@zwackelmann.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
......@@ -34,14 +48,26 @@ in the terminal. By default, the remote host will be called ``origin``, and the
git checkout --track origin/<branch>
from a terminal inside the repository folder. Refer to our `Git Tutorial <http://shangrila.iup.uni-heidelberg.de:30000/dorie/dorie/wikis/git-tutorial>`_ for more information on using Git.
from a terminal inside the repository folder. Refer to the `Atlassian Git Tutorial <https://www.atlassian.com/git>`_ for more information on using Git.
Preparations
############
OSX
---
.. _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 DORiE into a Docker image and then execute a container from it for your computations. 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
==========================
macOS
-----
The first thing you will have to do is to install Apple's Command Line Tools which
are bundled into the XCode software package. On more recent versions of OSX, this
can be done conveniently by executing
......@@ -68,141 +94,15 @@ You are now ready to :ref:`install DORiE <installation>`.
Linux
-----
Since there is a multitude of different Linux distributions, we cannot provide
installation instructions for all of them. DORiE is regularly tested on Ubuntu
14.04 LTS, 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
:ref:`installation <installation>` right away.
On any other distribution, you are responsible for installing the binary dependencies
yourself before proceeding. Running :option:`install.sh --no-deps` will tell you
which binary packages need to be installed. After ``install.sh --no-deps`` ran
successfully, you may proceed with using :ref:`doriecontrol`.
.. _installation:
Installation
############
The easiest way to install DORiE is to use the installation scripts provided. The first one is called
:ref:`install.sh` and is a simple shell script that
- tries to install some large binary dependencies through your system's package manager (MacPorts on OSX, :command:`apt-get` on Linux),
- creates symbolic links in the :file:`links/` folder, to set the standard software used by DORiE,
- sets the path to your installation in the :ref:`doriecontrol` and :ref:`dorie` scripts,
- places symbolic links to those two scripts into :file:`/usr/local/bin`, so you can call them from anywhere.
After cloning the repository, you can just execute the installation script by opening a Terminal, navigating to the repository
and executing the command
.. code-block:: shell
bash install.sh
.. _doriecontrol:
After the script ran successfully, you are ready to use ``doriecontrol``. Call
.. code-block:: shell
doriecontrol install core
(only installs minimum libraries to run DORiE)
or
.. code-block:: shell
doriecontrol install all
(installs additional tools to build the documentation or run system tests)
from anywhere on your computer, and all dependencies will be installed along with DORiE.
If you did not encounter any errors and DORiE was installed successfully, you are ready
to start :ref:`your first run <quickstart-cookbook>`!
Customize your installation
###########################
There are multiple ways to customize your installation, in case you want to change how dependencies
are handled, customize the folder structure, or to resolve errors.
Options for install.sh
----------------------
.. _install.sh:
.. object:: install.sh
This script accepts various command line arguments:
.. program:: install.sh
.. option:: --no-deps
Skips the installation of binary dependencies.
.. option:: --local <FOLDER>
Keeps everything local, preventing DORiE from installing
anything system-wide. Use this if you do not have :command:`sudo` access.
FOLDER points to the path where the symbolic links to :ref:`doriecontrol` and :ref:`dorie`
are placed. This makes it e.g. possible to use :file:`~/bin` as an installation location,
which is on the system :envvar:`PATH` on many operating systems.
.. option:: --system-mp
Forces this script to use the first MacPorts executable found, even when installing with
:option:`install.sh --local`. Use this on OSX, if you already have MacPorts installed and
want DORiE to use it.
.. option:: --serial
Builds MacPorts serially.
.. option:: --parallel <NPROC>
Builds MacPorts in parallel on NPROC processes (default: number of CPUs)
Change standard packages
------------------------
:ref:`install.sh` creates links to some third-party software required to install DORiE
(such as the GNU compilers, or Python) in the :file:`links/` folder, located in the
parent folder of the repository.
If for some reason you would like DORiE to use a different version than the one
:ref:`install.sh` has auto-detected for you, or if the auto-detection has failed,
you can just change the symbolic links there using the :cmd:`ln -s` shell command.
One example: (assuming your current working directory is the repository folder)
.. code-block:: shell
rm links/gcc links/g++ links/gfortran
ln -s /usr/bin/gcc-4.8 links/gcc
ln -s /usr/bin/g++-4.8 links/gcc
ln -s /usr/bin/gfortran-4.8 links/gcc
This makes DORiE use version 4.8 of the GNU compilers instead of version 5.x.
On any other distribution, the procedure of installing dependencies might differ from the step-by-step instructions supplied in :doc:`the ReadMe <README>`.
Installing DORiE into a custom DUNE environment
-----------------------------------------------
Even though the DORiE installation is designed to be as easy as possible, advanced users
might want to install DORiE into a custom DUNE environment (e.g. because they already
have an installation of DUNE on their machine and are comfortable with installing all
dependencies themselves). This way to install DORiE, albeit not officially supported,
is certainly possible. It should be sufficient to copy the folder :file:`dorie/` into
your DUNE environment and install it with ``dunecontrol``.
Windows
-------
Local builds of DUNE and DORiE on Windows are not supported. Please use the Docker installation variant on this system. Docker is available for 64-bit versions of Windows 7 or later. We recommend using Windows 10 Professional or Enterprise. Please refer to the Docker Manual on Windows for further details.
In case you run into errors, you can have a look at the file :file:`doriecontrol.in`,
especially at the creation of the :file:`dune.opts`-file.
If you run another version of Windows than the recommended ones, you have to install the `Docker Toolbox <https://docs.docker.com/toolbox/overview/>`_, to enable the virtualization features necessary for Docker.
Sphinx
sphinx_rtd_theme
breathe
recommonmark
\ No newline at end of file
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