merged doc into develop

.readthedocs.yml

+version: 2
+
+python:
+  version: 3.7
+  install:
+    - requirements: doc/requirements.txt
+
+sphinx:
+  builder: html
+  configuration: doc/conf.py
+
+submodules:
+  exclude: all
+
+formats: []

README.md

-[![pipeline status](https://git.scc.kit.edu/rtsn/rtsn/badges/master/pipeline.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master) [![coverage report](https://git.scc.kit.edu/rtsn/rtsn/badges/master/coverage.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master)
+[![pipeline status](https://git.scc.kit.edu/rtsn/rtsn/badges/master/pipeline.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master) [![coverage report](https://git.scc.kit.edu/rtsn/rtsn/badges/master/coverage.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master) [![Documentation Status](https://readthedocs.org/projects/kit-rt/badge/?version=latest)](https://kit-rt.readthedocs.io/en/latest/?badge=latest)
 
 # KiT-RT - an HPC Radio Therapy $`S_n`$ framework
 TBD 
@@ -152,13 +152,13 @@ This last step requires a preceeding `docker login`. Ask Jannick for login crede
 ## Code structure
 **WARNING: is not created automatically - might be out of date!**
 Reverse engineered plantuml diagram of the current code structure: 
-![Can't load image](doc/KiT-RT.svg "UML diagram")
+![Can't load image](doc/images/uml.svg "UML diagram")
 <br/><br/>
 Was created using [hpp2plantuml](https://github.com/thibaultmarin/hpp2plantuml) and [plantuml](https://plantuml.com/), e.g.:
 ```bash
 cd doc 
-hpp2plantuml -i "../code/include/*.h" -i "../code/include/*/*.h" -o KiT-RT.puml
-plantuml KiT-RT.puml -tsvg
+hpp2plantuml -i "../code/include/*.h" -i "../code/include/*/*.h" -o uml.puml
+plantuml uml.puml -tsvg
 ```
 
 ---

code/CMakeLists.txt

@@ -4,8 +4,10 @@ project( KiT-RT VERSION 0.1.0 LANGUAGES CXX )
 ### OPTIONS #####################################
 option( BUILD_TESTS "builds all available unit tests" OFF )
 option( BUILD_GUI "additionally builds a user interface" OFF )
+option( BUILD_DOC "builds Doxygen and Sphinx documentation" OFF )
 #################################################
 
+
 ### COMPILER ####################################
 set( CMAKE_CXX_STANDARD 17 )
 set( CMAKE_CXX_STANDARD_REQUIRED ON )
@@ -97,6 +99,8 @@ if( BUILD_TESTS )
     set( CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/ext/Catch2/contrib ${CMAKE_MODULE_PATH} )
     include( Catch )
     set( CATCH_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/ext/Catch2/single_include/catch2 )
+    add_compile_definitions( BUILD_TESTING )
+    add_compile_definitions( TESTS_PATH="${CMAKE_SOURCE_DIR}/tests/" )
     add_library( Catch INTERFACE )
     target_include_directories( Catch INTERFACE ${CATCH_INCLUDE_DIR} )
     file( GLOB_RECURSE TEST_SRCS RELATIVE ${CMAKE_SOURCE_DIR} "tests/*.cpp" )
@@ -138,3 +142,40 @@ if( BUILD_GUI )
     target_compile_options( ${CMAKE_PROJECT_NAME}_gui PUBLIC "$<$<CONFIG:RELEASE>:${KITRT_RELEASE_OPTIONS}>" )
 endif()
 #################################################
+
+
+### BUILD DOCUMENTATION #########################
+if( BUILD_DOC )
+    find_package( Doxygen REQUIRED )
+    find_package( Sphinx REQUIRED )
+
+    file( GLOB_RECURSE DOC_HEADER RELATIVE ${CMAKE_SOURCE_DIR} "include/*.h" )
+
+    set( DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR} )
+    set( DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen )
+    set( DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html )
+    set( DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/../doc/Doxyfile.in )
+    set( DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile )
+    configure_file( ${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY )
+    file( MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR} )
+    add_custom_command( OUTPUT ${DOXYGEN_INDEX_FILE}
+                        DEPENDS ${DOC_HEADER}
+                        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+                        MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
+                        COMMENT "Generating documentaion with Doxygen"
+                        VERBATIM )
+    add_custom_target( Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE} )
+
+    set( SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/../doc )
+    set( SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/sphinx )
+    set( SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html )
+    add_custom_command( OUTPUT ${SPHINX_INDEX_FILE}
+                        COMMAND ${SPHINX_EXECUTABLE} ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                        DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../doc/index.rst ${DOXYGEN_INDEX_FILE}
+                        MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+                        COMMENT "Converting documentation from Doxygen to Sphinx" )
+
+    add_custom_target( Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE} )
+endif()
+#################################################

code/cmake/FindSphinx.cmake

+find_program( SPHINX_EXECUTABLE
+              NAMES sphinx-build
+              DOC "Path to sphinx-build executable" )
+
+include( FindPackageHandleStandardArgs )
+
+find_package_handle_standard_args( Sphinx
+                                   "Failed to find sphinx-build executable"
+                                   SPHINX_EXECUTABLE )

doc/_static/theme_overrides.css

+.wy-side-nav-search {
+    background-color: #009682;
+}
+
+.wy-nav-side {
+    background: #009682;
+}

doc/authors.rst

+.. _authors:
+
+Authors
+------------------
+
+*****************
+KiT-RT Software
+*****************
+
++--------------------+------------------------+
+|Main contributors   | - Jannick Wolters      |
+|                    | - Jonas Kusch          |
+|                    | - Steffen Schotthöfer  |
+|                    | - Tianbai Xiao         |
+|                    | - Pia Stammer          |
++--------------------+------------------------+
+|Other contributors  |                        |
++--------------------+------------------------+
+
+*********************
+KiT-RT Dokumentation
+*********************
+
++--------------------+------------------------+
+|Main authors        | - Jannick Wolters      |
+|                    | - Jonas Kusch          |
+|                    | - Steffen Schotthöfer  |
+|                    | - Tianbai Xiao         |
+|                    | - Pia Stammer          |
++--------------------+------------------------+
+|Other contributors  |                        |
++--------------------+------------------------+
\ No newline at end of file

doc/common/config.rst

+Config
+======
+
+.. doxygenclass:: Config
+   :members:

doc/common/index.rst

+Common
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   config
+   mesh

doc/common/mesh.rst

+Mesh
+====
+
+.. doxygenclass:: Mesh
+    :members:

doc/conf.py

+import subprocess, os
+
+project = 'KiT-RT'
+copyright = '2021, Karlsruhe Institute of Technology'
+author = 'Jonas Kusch, Steffen Schotthöfer, Pia Stammer, Jannick Wolters, Tianbai Xiao'
+
+version = 'v0.1'
+release = 'v0.1'
+
+
+extensions = [
+    'breathe',
+    'sphinx_rtd_theme'
+]
+
+#templates_path = ['_templates']
+master_doc = 'index'
+exclude_patterns = []
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'logo_only': True,
+    'display_version': True,
+}
+html_logo = 'images/KiT-RT_logo_small.png'
+html_static_path = ['_static']
+def setup(app):
+    app.add_css_file('theme_overrides.css')
+
+breathe_projects = {
+    "KiT-RT": "../code/build/debug/docs/doxygen/xml",
+}
+
+breathe_default_project = "KiT-RT"
+
+read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+if read_the_docs_build:
+    inputDir = '../code'
+    outputDir = '../code/build/debug/docs/doxygen'
+    if not os.path.exists(outputDir):
+        os.makedirs(outputDir)
+    with open("Doxyfile.in", "rt") as fin:
+        with open("Doxyfile", "wt") as fout:
+            for line in fin:
+                line = line.replace('GENERATE_HTML          = YES', 'GENERATE_HTML          = NO')
+                line = line.replace('SEARCH_INCLUDES        = YES', 'SEARCH_INCLUDES        = NO')
+                line = line.replace('CLASS_DIAGRAMS         = YES', 'CLASS_DIAGRAMS         = NO')
+                line = line.replace('@DOXYGEN_OUTPUT_DIR@', outputDir)
+                line = line.replace('@DOXYGEN_INPUT_DIR@', inputDir)
+                fout.write(line)
+    subprocess.call('doxygen', shell=True)

doc/configFiles.rst

+Configuration files
+-----------------------
+
+Configuration files are written in `TOML-style <https://github.com/toml-lang/toml>`_
+. A number of examples (link examples) can be found in the ``./code/input`` folder. Users can also handover their own files, which should follow the following specifications:
+
+********************
+Parameters
+********************
+
+Below you can see the possible parameters that can be specified in a config file. Which of these parameters are required depends on the chosen application and solver
+
+
+
+.. code-block:: c++
+
+    // --- Options ---
+    // File Structure
+    std::string _inputDir;     // Directory for input files
+    std::string _outputDir;    // Directory for output files
+    std::string _outputFile;   // Name of output file
+    std::string _logDir;       // Directory of log file
+    std::string _logFileName;  // Name of log file
+    std::string _meshFile;     // Name of mesh file
+    std::string _ctFile;       // Name of CT file
+
+    // Quadrature
+    QUAD_NAME _quadName;       // Quadrature Name
+    unsigned short _quadOrder; // Quadrature Order
+    unsigned _nQuadPoints;
+
+    // Mesh
+    unsigned _nCells;
+
+    // Solver
+    double _CFL;                     // CFL Number for Solver
+    double _tEnd;                    // Final Time for Simulation 
+    PROBLEM_NAME _problemName;       // Name of predefined Problem   
+    SOLVER_NAME _solverName;         // Name of the used Solver 
+    ENTROPY_NAME _entropyName;       // Name of the used Entropy Functional 
+    unsigned short _maxMomentDegree; // Maximal Order of Moments for PN and MN Solver 
+    unsigned short _reconsOrder;     // Spatial Order of Accuracy for Solver 
+
+    // Linesource
+    double _sigmaS; // Scattering coeffient for Linesource test case 
+
+    /*If true, very low entries (10^-10 or smaller) of the flux matrices will be set to zero,
+     * to improve floating point accuracy */
+    bool _cleanFluxMat;
+
+    /*If true, the SN Solver uses all Gauss pts in the quadrature */
+    bool _allGaussPts; 
+    
+    /*If true, continuous slowing down approximation will be used */
+    bool _csd;                 
+
+    std::string _hydrogenFile; // Name of hydrogen cross section file 
+    std::string _oxygenFile;   // Name of oxygen cross section file 
+
+    // Boundary Conditions
+    /*List of all Pairs (marker, BOUNDARY_TYPE), e.g. (farfield,DIRICHLET).
+     *Each Boundary Conditions must have an entry in enum BOUNDARY_TYPE*/
+    std::vector<std::pair<std::string, BOUNDARY_TYPE>> _boundaries;
+
+    unsigned short _nMarkerDirichlet;          // Number of Dirichlet BC markers. Enum entry: DIRICHLET 
+    unsigned short _nMarkerNeumann;            // Number of Neumann BC markers. Enum entry: Neumann 
+    std::vector<std::string> _MarkerDirichlet; // Dirichlet BC markers. 
+    std::vector<std::string> _MarkerNeumann;   // Neumann BC markers. 
+
+    // Scattering Kernel
+    KERNEL_NAME _kernelName; // Scattering Kernel Name
+
+    // Optimizer
+    OPTIMIZER_NAME _entropyOptimizerName; // Choice of optimizer 
+    double _optimizerEpsilon;             // termination criterion epsilon for Newton Optmizer 
+    unsigned short _newtonIter;           // Maximal Number of newton iterations 
+    double _newtonStepSize;               // Stepsize factor for newton optimizer 
+    unsigned short _newtonLineSearchIter; // Maximal Number of line search iterations for newton optimizer 
+    bool _newtonFastMode;                 // If true, we skip the NewtonOptimizer for quadratic entropy and assign alpha = u 
+
+    // Output Options
+    unsigned short _nVolumeOutput;            // Number of volume outputs 
+    std::vector<VOLUME_OUTPUT> _volumeOutput; // Output groups for volume output
+    unsigned short _volumeOutputFrequency;    // Frequency of vtk write of volume output
+
+    unsigned short _nScreenOutput;            // Number of screen outputs 
+    std::vector<SCALAR_OUTPUT> _screenOutput; // Output groups for screen output
+    unsigned short _screenOutputFrequency;    // Frequency of screen output
+
+    unsigned short _nHistoryOutput;            // Number of screen outputs 
+    std::vector<SCALAR_OUTPUT> _historyOutput; // Output groups for screen output
+    unsigned short _historyOutputFrequency;    // Frequency of screen output
+
+
+
+

doc/cpp_doc.rst

+C++ Documentation
+=================
+
+.. image:: images/uml.svg
+  :width: 800
+  :alt: UML diagram
+
+.. toctree::
+   :maxdepth: 2
+   
+   common/index
+   entropies/index
+   fluxes/index
+   kernels/index
+   optimizers/index
+   problems/index
+   quadratures/index
+   solvers/index
+   toolboxes/index

doc/developer_guide.rst

+================
+Developer Guide
+================
+

doc/entropies/entropybase.rst

+EntropyBase
+===========
+
+.. doxygenclass:: EntropyBase
+   :members:

doc/entropies/index.rst

+Entropies
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   entropybase
+   maxwellboltzmannentropy
+   quadraticentropy
\ No newline at end of file

doc/entropies/maxwellboltzmannentropy.rst

+MaxwellBoltzmannEntropy
+=======================
+
+.. doxygenclass:: MaxwellBoltzmannEntropy
+   :members:

doc/entropies/quadraticentropy.rst

+QuadraticEntropy
+================
+
+.. doxygenclass:: QuadraticEntropy
+   :members:

doc/fluxes/index.rst

+Fluxes
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   numericalflux
+   laxfriedrichsflux
+   upwindflux
\ No newline at end of file

doc/fluxes/laxfriedrichsflux.rst

+LaxFriedrichsFlux
+=================
+
+.. doxygenclass:: LaxFriedrichsFlux
+   :members: