From 19a0c964fbfe45f6a35c4173671f53203aca4c0b Mon Sep 17 00:00:00 2001
From: Stephan Schulz <stephan.schulz-x2q@rub.de>
Date: Thu, 26 Nov 2020 14:35:36 +0100
Subject: [PATCH] update sphinx documentation (#31)

---
 docs/CMakeLists.txt            | 14 +++---
 docs/api/ALL.rst               |  8 ++++
 docs/api/ALL_Point.rst         |  8 ++++
 docs/api/ALL_module.rst        | 87 ++++++++++++++++++++++++++++++++++
 docs/api/CustomExceptions.rst  | 44 +++++++++++++++++
 docs/api/index.rst             | 16 +++++++
 docs/classes/ALL.rst           |  9 ----
 docs/classes/ALL_Functions.rst |  7 ---
 docs/classes/ALL_Histogram.rst | 10 ----
 docs/classes/ALL_LB.rst        |  9 ----
 docs/classes/ALL_Point.rst     |  9 ----
 docs/classes/ALL_Staggered.rst | 10 ----
 docs/classes/ALL_Tensor.rst    |  9 ----
 docs/classes/ALL_Voronoi.rst   |  9 ----
 docs/conf.py.in                | 17 ++++++-
 docs/full/complete.rst         |  7 ---
 docs/index.rst                 | 19 +++-----
 17 files changed, 193 insertions(+), 99 deletions(-)
 create mode 100644 docs/api/ALL.rst
 create mode 100644 docs/api/ALL_Point.rst
 create mode 100644 docs/api/ALL_module.rst
 create mode 100644 docs/api/CustomExceptions.rst
 create mode 100644 docs/api/index.rst
 delete mode 100644 docs/classes/ALL.rst
 delete mode 100644 docs/classes/ALL_Functions.rst
 delete mode 100644 docs/classes/ALL_Histogram.rst
 delete mode 100644 docs/classes/ALL_LB.rst
 delete mode 100644 docs/classes/ALL_Point.rst
 delete mode 100644 docs/classes/ALL_Staggered.rst
 delete mode 100644 docs/classes/ALL_Tensor.rst
 delete mode 100644 docs/classes/ALL_Voronoi.rst
 delete mode 100644 docs/full/complete.rst

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 666f0a3..ee2de3d 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -17,6 +17,7 @@ find_package(Sphinx REQUIRED)
 #if(NOT ${BREATHE_NOT_FOUND} EQUAL 0)
 #	message( FATAL_ERROR "Python \"breathe\" package not found")
 #endif()
+# todo(s.schulz): Also find recommonmark
 #do we need to make sure sphinx_rtd_theme is installed?
 
 # Find all public headers
@@ -37,10 +38,6 @@ set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${PROJECT_SOURCE_DIR}/README.md)
 # configure doxygen config file
 configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
-set(SPHINX_IN ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
-set(SPHINX_OUT ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
-configure_file(${SPHINX_IN} ${SPHINX_OUT} @ONLY)
-
 # create doxygen output directory
 file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
 
@@ -60,12 +57,17 @@ set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
 set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
 set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
 
+set(SPHINX_IN ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
+set(SPHINX_OUT ${CMAKE_CURRENT_BINARY_DIR}/conf.py)
+set(SPHINX_BREATHE_PROJECT_PATH ${DOXYGEN_OUTPUT_DIR}/xml)
+configure_file(${SPHINX_IN} ${SPHINX_OUT} @ONLY)
+
 
+# todo(s.schulz): Add dependencies to all .rst files
 add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
                   COMMAND
                   ${SPHINX_EXECUTABLE} -b html
-                  -Dbreathe_projects.ALL=${DOXYGEN_OUTPUT_DIR}/xml
-		  -c "${CMAKE_CURRENT_BINARY_DIR}"
+                  -c "${CMAKE_CURRENT_BINARY_DIR}"
                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                   DEPENDS 
diff --git a/docs/api/ALL.rst b/docs/api/ALL.rst
new file mode 100644
index 0000000..b91fc10
--- /dev/null
+++ b/docs/api/ALL.rst
@@ -0,0 +1,8 @@
+.. _ALLClass:
+
+ALL class
+=========
+
+.. doxygenclass:: ALL::ALL
+
+.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
diff --git a/docs/api/ALL_Point.rst b/docs/api/ALL_Point.rst
new file mode 100644
index 0000000..1ff5eaa
--- /dev/null
+++ b/docs/api/ALL_Point.rst
@@ -0,0 +1,8 @@
+.. _PointClass:
+
+Point class
+===========
+
+.. doxygenclass:: ALL::Point
+
+.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
diff --git a/docs/api/ALL_module.rst b/docs/api/ALL_module.rst
new file mode 100644
index 0000000..6d889eb
--- /dev/null
+++ b/docs/api/ALL_module.rst
@@ -0,0 +1,87 @@
+.. _ALLModule:
+
+ALL Fortran module
+==================
+
+Due to the case insensitive nature of Fortran and the used toolchain
+(doxygen and sphinx), all variables and function names are lowercase on
+this page. We do, however, use only upper case for global constants, such
+as the load balancing methods (``ALL_STAGGERED`` etc.) and the function
+names are usually written similarly to MPI as ``ALL_get_work``. The object
+is of ``type(ALL_t)``.
+
+Methods
+-------
+Available methods are:
+
+.. doxygenvariable:: all_histogram
+.. doxygenvariable:: all_staggered
+.. doxygenvariable:: all_tensor
+.. doxygenvariable:: all_unstructured
+.. doxygenvariable:: all_voronoi
+
+
+Errors
+------
+The exceptions map to the following error constants:
+
+.. doxygenvariable:: all_error_filesystem
+.. doxygenvariable:: all_error_generic
+.. doxygenvariable:: all_error_internal
+.. doxygenvariable:: all_error_invalidargument
+.. doxygenvariable:: all_error_invalidcommtype
+.. doxygenvariable:: all_error_outofbounds
+.. doxygenvariable:: all_error_pointdimensionmissmatch
+
+And the error message is returned in a string of length
+``ALL_ERROR_LENGTH``.
+
+Functions
+---------
+These function all have a corresponding call in the object, with the
+``ALL_`` stripped from the function name. So with an object named
+``balancer`` the function ``ALL_get_work(balancer, work)`` is identical to
+``balancer%get_work(work)``. The following functions are available:
+
+.. doxygenfunction:: all_balance
+.. doxygenfunction:: all_finalize
+.. doxygenfunction:: all_setup
+
+Getters
+*******
+.. doxygenfunction:: all_get_dimension
+.. doxygenfunction:: all_get_gamma
+.. doxygenfunction:: all_get_length_of_work
+.. doxygenfunction:: all_get_neighbors
+.. doxygenfunction:: all_get_number_of_neighbors
+.. doxygenfunction:: all_get_number_of_vertices
+.. doxygenfunction:: all_get_prev_vertices
+.. doxygenfunction:: all_get_vertices
+.. doxygenfunction:: all_get_vertices_alloc
+.. doxygenfunction:: all_get_work
+.. doxygenfunction:: all_get_work_array
+
+Setters
+*******
+.. doxygenfunction:: all_set_gamma
+.. doxygenfunction:: all_set_method_data_histgram
+.. doxygenfunction:: all_set_min_domain_size
+.. doxygenfunction:: all_set_proc_grid_params
+.. doxygenfunction:: all_set_proc_tag
+.. doxygenfunction:: all_set_sys_size
+.. doxygenfunction:: all_set_vertices
+.. doxygenfunction:: all_set_work
+.. doxygenfunction:: all_set_work_multi
+
+Output
+******
+.. doxygenfunction:: all_print_vtk_outlines
+.. doxygenfunction:: all_print_vtk_vertices
+
+Error handling
+**************
+.. doxygenfunction:: all_error
+.. doxygenfunction:: all_error_description
+.. doxygenfunction:: all_reset_error
+
+.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
diff --git a/docs/api/CustomExceptions.rst b/docs/api/CustomExceptions.rst
new file mode 100644
index 0000000..d6d55b1
--- /dev/null
+++ b/docs/api/CustomExceptions.rst
@@ -0,0 +1,44 @@
+.. _CustomExceptions:
+
+Custom Exceptions
+=================
+
+The library may throw one of these exceptions, which are all based on
+``ALL::CustomException``.
+
+``CustomException``
+-------------------
+.. doxygenstruct:: ALL::CustomException
+  :outline:
+
+``FilesystemErrorException``
+****************************
+.. doxygenstruct:: ALL::FilesystemErrorException
+  :outline:
+
+``InternalErrorException``
+****************************
+.. doxygenstruct:: ALL::InternalErrorException
+  :outline:
+
+``InvalidArgumentException``
+****************************
+.. doxygenstruct:: ALL::InvalidArgumentException
+  :outline:
+
+``InvalidCommTypeException``
+****************************
+.. doxygenstruct:: ALL::InvalidCommTypeException
+  :outline:
+
+``OutOfBoundsException``
+****************************
+.. doxygenstruct:: ALL::OutOfBoundsException
+  :outline:
+
+``PointDimensionMissmatchException``
+****************************
+.. doxygenstruct:: ALL::PointDimensionMissmatchException
+  :outline:
+
+.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
diff --git a/docs/api/index.rst b/docs/api/index.rst
new file mode 100644
index 0000000..b64f7c3
--- /dev/null
+++ b/docs/api/index.rst
@@ -0,0 +1,16 @@
+Public API Reference
+====================
+
+.. toctree::
+  :maxdepth: 2
+  :caption: API
+
+  ALL.rst
+  CustomExceptions.rst
+  ALL_Point.rst
+  ALL_module.rst
+
+These pages should give a short overview of the public API
+
+
+.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
diff --git a/docs/classes/ALL.rst b/docs/classes/ALL.rst
deleted file mode 100644
index 468be03..0000000
--- a/docs/classes/ALL.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-===
-ALL
-===
-
-.. doxygenclass:: ALL::ALL
-   :members:
-   :protected-members:
-   :private-members:
-   :undoc-members:
diff --git a/docs/classes/ALL_Functions.rst b/docs/classes/ALL_Functions.rst
deleted file mode 100644
index 4e72896..0000000
--- a/docs/classes/ALL_Functions.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-======================
-ALL_Functions overview
-======================
-
-.. doxygennamespace:: ALL::Functions
-   :project: ALL
-
diff --git a/docs/classes/ALL_Histogram.rst b/docs/classes/ALL_Histogram.rst
deleted file mode 100644
index 8e2fafa..0000000
--- a/docs/classes/ALL_Histogram.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-=============
-ALL_Histogram
-=============
-
-.. doxygenclass:: ALL::Histogram_LB
-   :members:
-   :protected-members:
-   :private-members:
-   :undoc-members:
-
diff --git a/docs/classes/ALL_LB.rst b/docs/classes/ALL_LB.rst
deleted file mode 100644
index d065513..0000000
--- a/docs/classes/ALL_LB.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-=============
-ALL_LB
-=============
-
-.. doxygenclass:: ALL::LB
-   :members:
-   :protected-members:
-   :private-members:
-   :undoc-members:
diff --git a/docs/classes/ALL_Point.rst b/docs/classes/ALL_Point.rst
deleted file mode 100644
index 76a95c0..0000000
--- a/docs/classes/ALL_Point.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-=============
-ALL_Point
-=============
-
-.. doxygenclass:: ALL::Point
-   :members:
-   :protected-members:
-   :private-members:
-   :undoc-members:
diff --git a/docs/classes/ALL_Staggered.rst b/docs/classes/ALL_Staggered.rst
deleted file mode 100644
index 2889690..0000000
--- a/docs/classes/ALL_Staggered.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-=============
-ALL_Staggered
-=============
-
-.. doxygenclass:: ALL::Staggered_LB
-   :members:
-   :protected-members:
-   :private-members:
-   :undoc-members:
-
diff --git a/docs/classes/ALL_Tensor.rst b/docs/classes/ALL_Tensor.rst
deleted file mode 100644
index 5386fc0..0000000
--- a/docs/classes/ALL_Tensor.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-==========
-ALL_Tensor
-==========
-
-.. doxygenclass:: ALL::Tensor_LB
-   :members:
-   :private-members:
-   :protected-members:
-   :undoc-members:
diff --git a/docs/classes/ALL_Voronoi.rst b/docs/classes/ALL_Voronoi.rst
deleted file mode 100644
index 03bd940..0000000
--- a/docs/classes/ALL_Voronoi.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-===========
-ALL_Voronoi
-===========
-
-.. doxygenclass:: ALL::Voronoi_LB
-   :members:
-   :private-members:
-   :protected-members:
-   :undoc-members:
diff --git a/docs/conf.py.in b/docs/conf.py.in
index 1a8868a..f43ddc6 100644
--- a/docs/conf.py.in
+++ b/docs/conf.py.in
@@ -13,13 +13,16 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+from recommonmark.parser import CommonMarkParser
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'ALL'
+project = '@PROJECT_NAME@'
 copyright = '2020, Rene Halver, Forschungszentrum Juelich GmbH'
 author = 'Rene Halver'
+version = '@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@'
+release = '@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@'
 
 
 # -- General configuration ---------------------------------------------------
@@ -32,6 +35,9 @@ extensions = [ "breathe" ]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+source_parseres = { '.md': CommonMarkParser }
+source_suffix = ['.rst', '.md']
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -50,5 +56,12 @@ html_theme = 'sphinx_rtd_theme'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_theme_options = {
+    'sticky_navigation': True,
+    'style_external_links': True,
+}
+
 # Breath Config
-breathe_default_project = "ALL"
\ No newline at end of file
+breathe_projects = {"ALL":"@SPHINX_BREATHE_PROJECT_PATH@"}
+breathe_default_project = "ALL"
+breathe_default_members = ('members', 'undoc-members')
diff --git a/docs/full/complete.rst b/docs/full/complete.rst
deleted file mode 100644
index 0155ae6..0000000
--- a/docs/full/complete.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-.. .. _classes/FullDocumentation
-
-.. ==================
-.. Full Documentation
-.. ==================
-
-.. .. doxygenindex:: 
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 55c09b1..71ffe99 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,22 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ALL auto generated documentation!
-============================================
+Welcome to the documentation of ALL
+===================================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-   :glob:
+  :maxdepth: 2
+  :caption: Contents:
 
-   classes/*
+  api/index.rst
 
-.. .. toctree::
-..    :maxdepth: 2
-..    :caption: Full documentation:
-..    :glob:
-      
-..    full/*
+todo(s.schulz): Link to doxygen documentation.
 
 Indices and tables
 ==================
@@ -28,3 +22,4 @@ Indices and tables
 
 .. * :ref:`modindex`
 
+.. vim: et sw=2 ts=2 tw=74 spell spelllang=en_us:
-- 
GitLab