Sphinx documentation

CMakeLists.txt

@@ -14,6 +14,8 @@ option( T8CODE_USE_SYSTEM_SC "Use system-installed sc library" OFF )
 option( T8CODE_USE_SYSTEM_P4EST "Use system-installed p4est library" OFF )
 
 option( BUILD_DOCUMENTATION "Build t8code's documentation" ON)
+option( BUILD_SPHINX_DOCUMENTATION "Build t8code's documentation using sphinx" OFF)
+
 
 if( NOT CMAKE_BUILD_TYPE )
     set( CMAKE_BUILD_TYPE "Release" )
@@ -84,3 +86,7 @@ endif()
 if ( BUILD_DOCUMENTATION ) 
     add_subdirectory( ${CMAKE_CURRENT_LIST_DIR}/doc )
 endif()
+
+if ( BUILD_SPHINX_DOCUMENTATION )
+    set (BUILD_DOCUMENTATION 1)
+endif()

cmake/FindSphinx.cmake

@@ -0,0 +1,11 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)

doc/CMakeLists.txt

@@ -1,28 +1,73 @@
-find_package(Doxygen REQUIRED)
+if(BUILD_DOCUMENTATION)
+    find_package(Doxygen REQUIRED)
+    if (DOXYGEN_FOUND)
+        set(DOXYGEN_OUTPUT_DIR ${PROJECT_BINARY_DIR}/doc)
+        set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
+        set(DOXYFILE_IN ${PROJECT_SOURCE_DIR}/doc/Doxyfile.in)
+        set(DOXYFILE_OUT ${PROJECT_BINARY_DIR}/doc/Doxyfile)
 
-if (DOXYGEN_FOUND)
-    set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
-    set(DOXYFILE_IN ${PROJECT_SOURCE_DIR}/doc/Doxyfile.in)
-    set(DOXYFILE_OUT ${PROJECT_BINARY_DIR}/doc/Doxyfile)
+        #The following options are used inside the do
+        set(top_srcdir ${PROJECT_SOURCE_DIR})
+        set(top_builddir ${PROJECT_BINARY_DIR})
 
-    #The following options are used inside the do
-    set(top_srcdir ${PROJECT_SOURCE_DIR})
-    set(top_builddir ${PROJECT_BINARY_DIR})
+        set(PACKAGE_NAME ${PROJECT_NAME})
+        set(VERSION ${T8_VERSION})
 
-    set(PACKAGE_NAME ${PROJECT_NAME})
-    set(VERSION ${T8_VERSION})
 
+        #Replace variables inside @@ with the current values
+        configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
-    #Replace variables inside @@ with the current values
+        add_custom_command( OUTPUT ${DOXYGEN_INDEX_FILE}
+                            DEPENDS ${T8_PUBLIC_HEADERS}
+                            COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT} 
+                            MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN} 
+                            COMMENT "Generating documentation"
+                            VERBATIM)
+
+        add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+    else (DOXYGEN_FOUND)
+        message(FATAL_ERROR "Doxygen need to be installed to generate the doxygen documentation")
+    endif (DOXYGEN_FOUND)
+endif(BUILD_DOCUMENTATION)
+
+if (BUILD_SPHINX_DOCUMENTATION)
+    set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+    find_package(Sphinx REQUIRED)
+
     configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
+
+    if (SPHINX_FOUND)
+        set(SPHINX_SOURCE ${PROJECT_SOURCE_DIR}/doc/source)
+        set(SPHINX_BUILD ${PROJECT_BINARY_DIR}/doc/sphinx)
+        set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+        set(CONF_FILE_IN ${SPHINX_SOURCE}/conf.in)
+        set(CONF_FILE_OUT ${SPHINX_SOURCE}/conf.py)
+
+        configure_file(${CONF_FILE_IN} ${CONF_FILE_OUT} @ONLY)
 
-    add_custom_command( OUTPUT ${DOXYGEN_INDEX_FILE}
-                        DEPENDS ${T8_PUBLIC_HEADERS}
-                        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT} 
-                        MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN} 
-                        COMMENT "Generating documentation")
+        # Only regenerate Sphinx when:
+        # - Doxygen has rerun
+        # - Our doc files have been updated
+        # - The Sphinx config has been updated
+        add_custom_command( OUTPUT ${SPHINX_INDEX_FILE}
+                            COMMAND ${SPHINX_EXECUTABLE} -b html
+                            # Tell Breathe where to find the Doxygen output
+                            -Dbreathe_projects.T8code=${DOXYGEN_OUTPUT_DIR}/xml
+                            ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+                            DEPENDS
+                            # Other docs files you want to track should go here (or in some variable)
+                            ${SPHINX_SOURCE}/index.rst
+                            ${DOXYGEN_INDEX_FILE}
+                            MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
+                            COMMENT "Generating documentation with Sphinx")
 
-    add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
-else (DOXYGEN_FOUND)
-    message(FATAL_ERROR "Doxygen need to be installed to generate the doxygen documentation")
-endif (DOXYGEN_FOUND)
+
+        # Nice named target so we can run the job easily
+        add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
+    else (SPHINX_FOUND)
+        message(FATAL_ERROR "Sphinx need to be installed to generate the doxygen documentation")
+    endif (SPHINX_FOUND)
+endif(BUILD_SPHINX_DOCUMENTATION)

doc/Doxyfile.in

@@ -2611,3 +2611,8 @@ GENERATE_LEGEND        = YES
 # The default value is: YES.
 
 DOT_CLEANUP            = YES
+
+GENERATE_XML           = YES
+
+XML_OUTPUT             = xml
+

doc/source/conf.in

@@ -0,0 +1,33 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 't8code'
+copyright = '2024, Johannes Holke, David Knapp, Sandro Elsweijer, Ioannis Lilikakis, Lukas Dreyer, Jakob Fußbroich, Carsten Burstedde, Chiara Hergl, Johannes Markert, Niklas Boeing, Florian Becker, Prasanna Ponnusamy'
+author = 'Johannes Holke, David Knapp, Sandro Elsweijer, Ioannis Lilikakis, Lukas Dreyer, Jakob Fußbroich, Carsten Burstedde, Chiara Hergl, Johannes Markert, Niklas Boeing, Florian Becker, Prasanna Ponnusamy'
+version = '@VERSION@'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [ "breathe", "sphinx.ext.mathjax", "sphinx.ext.graphviz" ]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_logo = '../../t8code_logo.png'
+
+# Breathe Configuration
+breathe_default_project = "T8code"
+breathe_implementation_filename_extensions = ['.c', '.cpp']

doc/source/index.rst

@@ -0,0 +1,73 @@
+.. t8code documentation master file, created by
+   sphinx-quickstart on Wed May 22 13:19:02 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to t8code's documentation!
+==================================
+This is the documentation for t8code version |version|
+
+Author
+======
+    Johannes Holke, David Knapp, Lukas Dreyer, Niklas Böing, Sandro Elsweijer, Ioannis Lilikakis, Veli Ünlü, Carsten Burstedde, Johannes Markert et. al. 
+
+Copyright
+=========
+    GNU General Public License version 2 (or, at your option, any later version)
+
+t8code (spoken as "tetcode") is a C/C++ library to manage parallel adaptive meshes with various element types. t8code uses a collection (a forest) of multiple connected adaptive space-trees in parallel and scales to at least one million MPI ranks and over 1 Trillion mesh elements.
+
+t8code is intended to be used as a thirdparty library for numerical simulation codes or any other applications that require meshes.
+
+The best place to start learning about t8code is the Wiki, especially the Installation Guide and the Tutorials.
+
+You find the source code to t8code on github.
+
+t8code supports the following element types (also different types in the same mesh):
+
+   - 0D: vertices
+   - 1D: lines
+   - 2D: quadrilaterals and triangles
+   - 3D: hexahedra, tetrahedra, prisms, and pyramids (currently in development).
+
+Among others, t8code offers the following functionalities:
+
+   - Create distributed adaptive meshes over complex domain geometries
+   - Adapt meshes according to user given refinement/coarsening criteria
+   - Establish a 2:1 balance
+   - (Re-)partition a mesh (and associated data) among MPI ranks
+   - Manage ghost (halo) elements and data
+   - Hierarchical search in the mesh
+
+t8code uses space-filling curves (SFCs) to manage the adaptive refinement and efficiently store the mesh elements and associated data. A modular approach makes it possible to exchange the underlying SFC without changing the high-level algorithms. Thus, we can use and compare different refinement schemes and users can implement their own refinement rules if so desired.
+
+Currently,
+
+   - lines use a 1D Morton curve with 1:2 refinement
+   - quadrilaterals/hexahedra are inherited from the p4est submodule, using the Morton curve 1:4, 1:8 refinement;
+   - triangles/tetrahedra are implemented using the Tetrahedral Morton curve, 1:4, 1:8 refinement;
+   - prisms are implemented using the triangular TM curve and a line curve, 1:8 refinement.
+   - pyramids are implemented via a pyramidal Morton code.
+   - The code supports hybrid meshes including any of the above element types (of the same dimension).
+
+You find more information on t8code in the t8code Wiki.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+Docs
+====
+
+.. doxygenindex::
+   :allow-dot-graphs:

src/t8_forest/t8_forest_private.h

@@ -52,7 +52,7 @@ T8_EXTERN_C_BEGIN ();
  *                  In the case of complete forests, the scheme based element 
  *                  function \see t8_element_is_family is recommended.
  * \note            If the element with id \a el_considered is not the first
- *                  family member, return 0. Therefore, if \return is x > 0, 
+ *                  family member, return 0. Therefore, if return is x > 0, 
  *                  the first x elements in \a elements form a family.
  */
 int